atomic-design-poc/.claude/skills/document-feature/SKILL.md

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: 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

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