---

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

When to skip

Gate carve-outs live in the haus CLI algorithm (not decisions-triggers.json). Use this table:

| Change | ADR needed? | | --- | --- | | Dependency version bump, no dep added/removed | No | | New or removed dependency | Yes | | Lockfile-only regen (no package.json change) | No | | Catalog sync (chore/sync-catalog-* branch, or library/catalog/**) | No | | Schema/migration/CI/infra/API-contract/auth path | Yes (security paths: [adr-skip] ignored) | | 8+ files across 2+ top-level dirs (not a dep bump) | Yes | | Docs/tests-only | No (already exempt) |

Workflow

1. Run haus decisions suggest (or use the Stop-hook JSON draft).
2. Present the draft to the user — never mark Accepted without explicit approval.
3. On approval: write docs/decisions/NNNN-slug.md and add a README index row with a one-line why.
4. 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
• Reach for [adr-skip] on security/auth paths — the gate ignores it; write the ADR instead

Commands

haus decisions suggest          # draft from staged/unstaged diff
haus decisions check --staged   # local gate
haus decisions next-number      # next NNNN
haus decisions validate path    # structure check

Index lives at docs/decisions/README.md — keep it @imported from CLAUDE.md.