Documentation and ADRs
Document the decision a future maintainer needs, not the whole conversation.
Documentation workflow
- Identify the reader, decision or task, freshness owner, and expected action.
- Inspect the source of truth, commands, configuration, and current behavior.
- Separate facts, assumptions, examples, and recommendations. Mark version or
environment-specific statements.
- Put the shortest usable path first; move exhaustive details to a linked
reference.
- Test every command, code sample, relative link, and stated file path that
the environment permits.
ADR workflow
Use an ADR when a choice affects interfaces, architecture, data, operations,
security, or future contributors. Record context, decision, alternatives,
consequences, rejected options, migration/rollback, and status. Do not use an
ADR to hide an unresolved decision; mark it proposed or superseded honestly.
Read adr-template.md. Keep README content as a
front door and link to deeper docs; avoid stale feature walls and hardcoded
claims that the repository cannot verify.
Completion condition
The intended reader can act from the document, links and examples resolve, and
the document's factual or verification limits are visible.
1---2name: documentation-and-adrs3description: Writes or updates engineering documentation and architecture decision records from repository facts, explicit assumptions, trade-offs, and verification links. Use for README changes, design docs, runbooks, ADRs, migration notes, and contributor documentation. Not for implementation planning alone or for copying external documentation without provenance.4---56# Documentation and ADRs78Document the decision a future maintainer needs, not the whole conversation.910## Documentation workflow11121. Identify the reader, decision or task, freshness owner, and expected action.132. Inspect the source of truth, commands, configuration, and current behavior.143. Separate facts, assumptions, examples, and recommendations. Mark version or15 environment-specific statements.164. Put the shortest usable path first; move exhaustive details to a linked17 reference.185. Test every command, code sample, relative link, and stated file path that19 the environment permits.2021## ADR workflow2223Use an ADR when a choice affects interfaces, architecture, data, operations,24security, or future contributors. Record context, decision, alternatives,25consequences, rejected options, migration/rollback, and status. Do not use an26ADR to hide an unresolved decision; mark it proposed or superseded honestly.2728Read [adr-template.md](references/adr-template.md). Keep README content as a29front door and link to deeper docs; avoid stale feature walls and hardcoded30claims that the repository cannot verify.3132## Completion condition3334The intended reader can act from the document, links and examples resolve, and35the document's factual or verification limits are visible.
thiientv