feature-docs
feature-docs
Feature docs preserve what a feature does, why choices were made, and what remains unverified for a reader without the original conversation. The local-markdown configuration of Matt Pocock's skills uses .scratch/<feature>/; consult docs/agents/issue-tracker.md when present rather than assuming every tracker uses local files.
Write three human documents under docs/<feature>/feature-docs/:
| File | Owns |
|---|---|
overview.md |
User problem, current capabilities, contracts, navigation and verification summary |
decisions.md |
Choices, recorded reasons, rejected alternatives and unresolved intent conflicts |
tickets.md |
Delivery slices, acceptance criteria, evidence and remaining checks |
sources.json |
Script-owned source, document and evidence baselines; never hand-edit |
One fact has one home; other files link to it by decision/ticket ID. Remove template writing instructions from finished docs; retain useful navigation and status legends. Use the local feature slug. The script is bash scripts/feature-docs.sh; read --help for command syntax. Read references/example.md when an evidence row or finished document is unclear.
Evidence and decisions
Code inspected supports only what the opened file/symbol demonstrates. Test passed requires an actual result, command, scope and date. Runtime verified requires an observed scenario, environment and date. Inherited results name their source and say not rerun. A test file is code evidence, not a passing result. Mark unsupported claims unverified, with the check still needed.