diff --git a/skills/agent-instructions/SKILL.md b/skills/agent-instructions/SKILL.md index 253fce4..b347572 100644 --- a/skills/agent-instructions/SKILL.md +++ b/skills/agent-instructions/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:agent-instructions description: This skill should be used when the user asks to "set up CLAUDE.md", "set up AGENTS.md", "agent instructions", "add engineering rules", "make the instructions thinner", or needs to establish or maintain a thin, multi-vendor root instruction file backed by on-demand engineering rules under docs/rules/. -version: 0.2.0 +version: 0.2.1 --- # Agent Instructions diff --git a/skills/agent-instructions/references/rules-doc-comments.md b/skills/agent-instructions/references/rules-doc-comments.md index 3593401..e60111d 100644 --- a/skills/agent-instructions/references/rules-doc-comments.md +++ b/skills/agent-instructions/references/rules-doc-comments.md @@ -58,9 +58,12 @@ than no comment. ## Never reference the issue tracker from source A doc comment, test name, or identifier must never name a tracked issue, -pull request, review round, or finding label — the reader of the code has no -guaranteed access to that system, and the reference rots the day the ticket -does. Write the reasoning the ticket stood for, in the code's own words, -even if that duplicates wording that also lives in the tracker. A path to -another file inside the same repository (a design doc, a decision record) is -fine, since anyone with the repository can open it. +pull request, review round, finding label, acceptance-criterion number +(`AC4`), or requirement/workstream label with no in-repo definition — the +reader of the code has no guaranteed access to that system, and the +reference rots the day the ticket does. Write the reasoning the ticket stood +for, in the code's own words, even if that duplicates wording that also +lives in the tracker. A path to another file inside the same repository (a +design doc, a decision record) is fine, since anyone with the repository can +open it. A label is canonical only if the repository itself defines it; a +delivery report merely quoting it does not count. diff --git a/skills/agent-instructions/references/rules-naming.md b/skills/agent-instructions/references/rules-naming.md index 8d8d9b2..162e35b 100644 --- a/skills/agent-instructions/references/rules-naming.md +++ b/skills/agent-instructions/references/rules-naming.md @@ -59,6 +59,21 @@ Add tokens only to restore domain or semantic context that would otherwise be lost — not to repeat an enclosing namespace or narrate implementation details already visible in the type. +## Names are never work-tracking coordinates + +A ticket ID, an acceptance-criterion number (`ac4`), a review-round or +finding label, or a requirement/workstream code with no in-repo definition +must not appear in an identifier, file, directory, binary, module, stack, or +test name. Such a name records where the work was tracked, not what the +thing is; a reader of the code has no guaranteed access to the tracker, and +the reference rots the day the ticket closes. Name the capability or +behavior instead — the binary that proves chain anchoring is +`chain-anchor-proof`, not `proj424-proof`. Citing an in-repo canonical +artifact (a decision record number, a `docs/…` path) is fine inside a +comment, but never as a substitute for a self-descriptive name. An existing +deployed identity that already carries such a name changes only under the +compatibility-aware rename rule below. + ## Renames are atomic and compatibility-aware Update every call site, import, test, and doc reference in the same change.