| name | adr-decisions |
| description | Draft and gate Architecture Decision Records (ADRs) when changes are decision-worthy. Use when `haus decisions suggest` fires, when adding deps/schema/auth/API changes, or when the user asks why a choice was made. Machine drafts; human approves. |
ADR decisions
Captures why significant choices were made under docs/decisions/.
Use when
haus decisions suggest or the Stop hook proposes an ADR
- A change touches dependencies, schema, auth, public APIs, CI, or infrastructure
- The user asks "why did we choose X?" before coding an alternative
Workflow
- Run
haus decisions suggest (or use the Stop-hook JSON draft).
- Present the draft to the user — never mark
Accepted without explicit approval.
- On approval: write
docs/decisions/NNNN-slug.md and add a README index row with a one-line why.
- Commit the ADR in the same PR as the code change.
Do not
- Hand-author ADRs without pulling context from the diff and conversation
- Skip the README index update
- Use
[adr-skip] for security/auth path changes (gate ignores skip)
Commands
haus decisions suggest
haus decisions check --staged
haus decisions next-number
haus decisions validate path
Index lives at docs/decisions/README.md — keep it @imported from CLAUDE.md.