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>
55 lines
2.7 KiB
Markdown
55 lines
2.7 KiB
Markdown
---
|
|
name: document-feature
|
|
description: 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: follow `docs/reference/roles-and-access.md` (H1 title, intro that links the
|
|
governing ADR/WP, task-oriented `##` sections, `## See also` footer 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`, then `Status: 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 of `docs/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
|
|
|
|
```bash
|
|
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
|
|
```
|