ehoandClaude Opus 5
12f17d9d73
Two backlog trees are complete: `docs/project/backlog/` (75 files, every WP done) and `docs/project/refactor-backlog-setup/` (the arc before it). Move both under `docs/project/archive/` with `git mv`, so history stays intact through `git log --follow`. `SHOWCASE-ROADMAP.md` moves with them, because it points at the now-archived backlog README. Add `docs/project/archive/README.md`. It states that these trees are historical and names the two directories that are still live. Repoint every inbound reference named in RD-30's Files table: CLAUDE.md, the root README, both backend READMEs, `LetterHtml.cs`, `a11y.mdx`, the `document-feature` and `new-ssp` skills, and the readable-codebase PLAN, README, and RD-19 ticket. Fix two upward-relative links inside the moved WP files (WP-68, WP-69) that gained a directory level and would otherwise break. Repoint `.prettierignore`'s two agent-prompt exclusions to their new path, so prettier keeps leaving those files' exact wording alone. Mark RD-30 done and check off its acceptance criteria; flip its README row to done. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.7 KiB
name, description
| name | description |
|---|---|
| document-feature | Ship docs in the same diff as the code — add a doc for a new feature, update the existing doc when a feature changes. Use whenever you add a feature or adjust one that is already documented. |
Document feature (docs travel with the code)
A feature change is not done until its docs match. Same diff, not a follow-up. Undocumented behavior is a bug; stale docs are worse than none.
New feature → add the right kind of doc
The repo splits docs by kind (docs/README.md). Pick one — don't write all three:
- Reference doc —
docs/reference/<name>.md. A stable "how it works + how to extend without coupling" page. Default for a feature others will build on or wire into. Shape: followdocs/reference/roles-and-access.md(H1 title, intro that links the governing ADR/WP, task-oriented##sections,## See alsofooter of backticked paths). - ADR —
docs/reference/architecture/NNNN-<slug>.md. Only when you're recording a decision/pattern (a tradeoff, a "we chose X over Y"). One format, no drift:# ADR-NNNN — Title, thenStatus: Accepted · Date: YYYY-MM-DD, then Problem / Options / Decision / Consequences. - WP —
docs/project/archive/backlog/WP-NN-<slug>.md. Tracked work; use the template at the bottom ofdocs/project/archive/backlog/README.md.
Then add the index row: docs/README.md table for a reference doc/ADR,
docs/project/archive/backlog/README.md for a WP. A doc with no index row is invisible.
Adjusted feature → update what already describes it
Before you call the change done: grep -ril <feature-name> docs/ and update every hit —
the reference doc's "how to extend" and coupling notes, the ADR's Consequences, the WP's
Outcome/Acceptance. If the change makes a doc claim false, fix the claim in this diff.
Coupling is the interesting part
For any feature others consume, the doc's most valuable section is how to extend it and
where the coupling lives — which shared seams it touches (ADMIN_LINKS, the
role.interceptor ROLE_AWARE list, Capability), and any hand-wired pattern a second
consumer would repeat. Name the coupling; recommend the abstraction only when a real
second case lands (don't refactor speculatively).
Worked examples
docs/reference/stamdata.md,docs/reference/audit-log.md,docs/reference/feature-flags.md— the three admin-feature reference docs.docs/reference/architecture/0004-stamdata-as-code.md— the decision behind stamdata.
Verify
grep -ril <feature-name> docs/ # every place that mentions it is current
grep -q "<new-doc-path>" docs/README.md # (or backlog/README.md) — index row exists