adr

Capture the why behind a choice so future agents and humans do not re-derive it. Every ADR includes the alternatives you rejected and a "Reconsider if" trigger that keeps it from becoming a tombstone.

When to use it

• A non-obvious technical choice was made.
• An obvious choice was made for a non-obvious reason.
• A non-choice was made deliberately. ("Considered GraphQL, stayed with REST because…")
• A constraint was discovered that will shape future decisions.
• audit flagged a recent merge as decision-shaped but ADR-less.

When not to

• Implementation details the code expresses well on its own.
• Preferences with no real tradeoff. Those go in AGENTS.md.
• Decisions still being debated. Wait until decided.

What it produces

• docs/decisions/<NNNN>-<slug>.md: the ADR.
• If missing: docs/decisions/README.md and docs/decisions/negative-space.md.
• A one-liner in AGENTS.md (or a docs/agents/ file) if the decision creates an ongoing rule.

How it works

Three input modes, detected from your first message:

• Live decision. You describe the choice. The command asks for the four things it needs.
• From a merged PR. Paste a PR URL. The command pulls title, description, files, reviews via gh pr view and pre-fills.
• From a commit range. Name commits or an area. The command reads git log / git diff and pre-fills.

1. Find the next number. Globs existing ADRs, takes the max, adds one.
2. Draft. Context names constraints, not background. Alternatives has at least one rejected option. Reconsider-if is specific. Title is the decision, not the topic.
3. Show the draft. ADRs are durable. A rushed one is worse than a delayed one.
4. Set status and write. accepted, proposed, or superseded by ADR-NNNN (with the older file updated).
5. Cross-link. Add a one-liner in AGENTS.md if the ADR creates an ongoing rule.
6. Negative-space sweep. Briefly considered options that do not warrant a full ADR get a paragraph in negative-space.md.