ehoandClaude Opus 4.8
cff711504f
Emphasis normalized to underscore; fixes red format:check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
55 lines
2.6 KiB
Markdown
55 lines
2.6 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/backlog/WP-NN-<slug>.md`. Tracked work; use the template at the
|
|
bottom of `docs/project/backlog/README.md`.
|
|
|
|
Then **add the index row**: `docs/README.md` table for a reference doc/ADR,
|
|
`docs/project/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
|
|
```
|