feat: coding standard durable references

[taminomara]

Summary

This PR changes the /coding-standard skill so the standards it generates cite code by durable anchors (an exported symbol or a stable doc heading) instead of bare file:line references and snapshot consumer lists, so that a generated standard stays accurate as the code it describes evolves instead of going stale.

• A standard produced by the skill used to point at code with bare line numbers and list "current consumers" by name. Both rot: inserting a line above a citation breaks it, and the consumer list drifts the moment consumers change. After this PR, every code citation names a durable anchor, and a rule's audience is written as a membership criterion (the property that defines the set, e.g. "any module that renders user-supplied HTML") rather than today's file roster.
• The behavior is governed by one new rule document read in two modes. Research mode (the dispatched evidence-gathering agent) resolves anchors and reports them with a line range as a navigation aid; authoring mode (drafting and verification) cites only the anchor and drops the range. The two modes share Rules 1-2; authoring adds Rules 3-4 (membership criterion, no temporal phrasing).
• One deliberate exception: if a project already cites with line numbers as its house style, the skill keeps that format but still requires the anchor alongside it. An anchorless line number is never emitted, house style or not.
• Scope is the /coding-standard skill only. No other skill, agent, or already-generated standard file is touched. Closes coding-standard skill generates standards that cite volatile codebase state, so produced standards go stale #73.

Behavior changes

When you run /coding-standard after this PR:

• The codebase-explorer agent it dispatches now returns, for each example, a file path, a line range, and one or more greppable durable anchors derived from the new rule. When no greppable anchor isolates the pattern, the place comes back flagged for engineer review instead of being cited coarsely.
• The drafting step cites each example by its anchor and drops the line range (kept only under a detected line-number house style), writes Applies To as a membership criterion, and removes temporal words like "today" / "currently" / "existing."
• The verification pass confirms the finished standard follows the durable-reference rule in authoring mode — re-reading both the standard body and its index-file entry for any line-position citation or temporal phrasing and rewriting or flagging them before the file is considered done.

What to look at first

• The two-mode split in durable-references.md is the core design decision: a researcher gathering evidence applies Rules 1-2 and is allowed to report line ranges, while the author applies all four and may not. Confirm that boundary reads cleanly, since the whole anti-staleness guarantee rests on the author never pasting the range through.
• Rule 2's scope decision tree and its escalation leaf. When nothing greppable isolates a pattern at acceptable granularity, the skill escalates to the engineer rather than emitting a coarse reference. Worth checking that "no boundary exists" is correctly excluded as a trigger (the whole file is always a fallback boundary) so escalation only fires for the intended "cleanest scope still drags in unrelated context" case.
• The house-style exception, now stated once in Rule 1 of durable-references.md (Step 6 authoring and Step 10 verification apply it rather than restating it). It is the one place a line number survives, and the constraint that it must always ride alongside an anchor — never anchorless — is the load-bearing rule.

How this was tested

• ✅ Ran an A/B dry-run on my code base from two baselines: one before the first standard ever appeared, another after a few were in place. Ran the same prompt — "extract section about background jobs from claude.md into a new coding standard" — once under the old skill and once under the new skill, in an isolated git worktree, and compared the two generated server-background-jobs.md files.
• ✅ Clean baseline (no pre-existing standards): the new skill produced 0 bare line-number citations versus the old skill's 16, citing every example by a durable anchor and writing Applies To as a membership criterion.
• ✅ House-style baseline (the project's existing standards all cite code by line number): the new skill produced 17 line-number citations, each paired with its symbol anchor, identically across three runs — matching the established house style rather than emitting anchorless line numbers.
• ✅ Confirmed the house-style run is what surfaced the Step 3.4 "match existing format" vs. durable-reference-rule conflict, which drove the house-style exception now stated in Rule 1 of the durable-reference rule.

Files of interest

• han-coding/...references/durable-references.md — the new rule; defines the two reader modes and all four rules.
• han-coding/skills/coding-standard/SKILL.md — wires the rule into Step 4 (research), Step 6 (authoring), and Step 10 (verification).
• han-coding/...standard/references/template.md — example reference reshaped to path, anchor — note.
• docs/skills/han-coding/coding-standard.md — operator doc refreshed to describe the anchored-citation behavior.

Notes

I did not include research docs and implementation specs/plans. Let me know if you want them.

[mxriverlynn]

this looks great! i ran it through a small project i've been working on, and the output was a significant improvement over the prior versions of the skill. thank you for this! i also wanted to note that i ran this through the /han-plugin-builder:guidance skill and it picked up a few things that should be corrected. can you read through these and either apply the suggestions, and/or provide feedback on them? thanks :)

---

Review summary: feat/coding-standard-durable-references

Reviewed against the skill-building guidance (progressive-disclosure.md, context-hygiene.md, writing-effective-instructions.md, skill-reference-files.md, script-execution-instructions.md).

What the branch does: adds han-coding/skills/coding-standard/references/durable-references.md (a new "cite code by durable anchors, not line numbers" rule), threads it through coding-standard/SKILL.md Steps 4/6/10, and updates the template + operator doc to match. The core idea is sound and the structural choices are mostly guidance-compliant. Findings below, ordered by impact.

What's already right (no change needed)

• Reference placement is correct. The rule is domain knowledge ("what to know"), and it lives in references/, not the skill root — exactly what skill-reference-files.md and progressive-disclosure.md prescribe (Level 3). The reference file correctly carries no paths: frontmatter, consistent with the skill's other references.
• Operator doc updated in lockstep (docs/skills/han-coding/coding-standard.md) — satisfies the documentation-maintenance expectation.
• Body is under the 500-line ceiling (256 lines).
• The rule embeds its reasoning (why bare file:line and "current consumers" rosters go stale), which matches the "constraints with embedded reasoning" rule.

1. Verbosity and duplication in the SKILL.md body (primary finding)

context-hygiene.md ("Every token must earn its place") and writing-effective-instructions.md ("Too verbose → Claude loses focus in long prose; say it once") both push against what this branch does: the durable-reference rule is now re-derived in dense prose in five body locations — Step 4 merge paragraph (line 102), Step 6 intro (line 120), Step 6.4 (line 131), Step 6.7 (line 146), and Step 10 checks 4b/4c (lines 247–248) — on top of the canonical reference file.

The sharpest example is Step 10 check 4b, which restates the entire citation-notation taxonomy (path:NNN, path:NNN-MMM, path:NNN:CC, path#LNN, (:NN), line N…) and the full temporal-word list (today / currently / now / existing / as of this writing / the current set of). That content already lives in the reference file's Rules 1, 3, and 4. The body should point to the reference for what the rule says and keep each step to the process action ("apply the rule's authoring mode at verification; flag any citation you can't re-anchor"). Recommend collapsing the inline re-derivations to short process instructions + a pointer, letting durable-references.md be the single source of the rule's content.

2. Unbalanced quote in the agent-2 dispatch prompt (cleanliness)

SKILL.md:100 — the standards-and-ADRs explorer prompt opens with " but the closing " was dropped in this edit (the pre-branch version ended …resolve or cite."). It now reads as an unterminated quoted string. Agent-1's prompt (line 95) still closes correctly. Small, but it's a regression this branch introduced.

3. Awkward orchestrator note wedged into Step 4 (lines 97–98)

The "Make sure to pass full path ${CLAUDE_SKILL_DIR}/… to the agent…" paragraph is an orchestrator-directed aside sitting inside the agent-dispatch list, oddly indented, and partly redundant — the agent prompt on line 95 already embeds that path. Either fold the intent into the prompt or cut it; as written it competes for attention without adding instruction.

4. ${CLAUDE_SKILL_DIR} used to pass a reference path to a dispatched agent (validated, note only)

script-execution-instructions.md documents ${CLAUDE_SKILL_DIR} for script paths. Using it to hand codebase-explorer an absolute path to a reference file is a new application of the convention. It's sound — expansion is body-wide so the absolute path is embedded before dispatch, and codebase-explorer has the Read tool — so no change is required. Flagging only because it's the first reference-path (vs. script-path) use of the variable in the suite.

5. Minor capitalization inconsistency

The agent-1 prompt says "rules 1 and 2" (lowercase) while the reference file and the rest of SKILL.md use "Rule 1", "Rules 1 and 2", "Rule 3" (capitalized). Trivial consistency nit.

Observation (not a change)

durable-references.md frames itself as applying to "a coding standard, a piece of project documentation," but only coding-standard consumes it today. Promoting it to a cross-skill reference (alongside han-coding/references/yagni-rule.md) would be premature now — YAGNI says wait for a second consumer (e.g. project-documentation). Worth keeping in mind if that second consumer appears.

Net: one cleanliness regression (item 2), and the substantive guidance issue is item 1 — the body restates the rule enough times to dilute the very attention the reference file was extracted to protect. None of this is blocking; all are tightening passes.

[taminomara]

Fixed, with two caveats:

• Regarding item 3. During test runs, I've noticed that main agent tends to rewrite sub-agent prompts in its own words. It often omits reference to durable-references.md and loosely rewrites it inline. If this becomes an issue, consider restoring this prompt nudge.
• Regarding "Observation (not a change)": the reason for this framing is that durable-references.md is consumed by sub-agents, which aren't (strictly speaking) aware that they were started from the coding-standard skill.

[taminomara]

One more caveat, completely removing duplication re-introduced temporal wording, so I had to add back a bit of enumeration in step 10. Overall, my experience is that some duplication is necessary even if it deludes context, especially with 1M variant. Also, expanded durable reference rules with new failure modes spotted in recent runs.