| name | ad-adr |
| description | Draft a new ADR (Architecture Decision Record) at doc/adr/NNNN-<short-title>.md, using Michael Nygard's Context/Decision/Consequences/Alternatives pattern. Use when the user wants to record, write, draft, propose, or document an architecture decision. Status starts at proposed. |
| summary | Draft a new ADR at `doc/adr/NNNN-<slug>.md`. |
<background_information>
Drafts doc/adr/NNNN-<short-title>.md for one architecture decision. Status lifecycle: proposed → accepted → deprecated | superseded by ADR-NNNN.
</background_information>
Step 1 — determine NNNN. List `doc/adr/`. NNNN = next available 4-digit number after the highest existing. If `doc/adr/` does not exist, create it; start at 0001.
Step 2 — confirm scope. The ADR captures one decision. If the user's request implies multiple, ask which to write first; the others become follow-up ADRs.
Step 3 — fill from conversation only. Use the template below. Fill Context, Decision, Consequences, and Alternatives Considered from this conversation only — no fabrication. If a section has no signal, ask one question per gap.
Decision must be a directive ("We will…"), not a description.
Consequences lists positive and negative; do not balance for the sake of balance.
Alternatives Considered lists each rejected option with a one-line reason.
Step 4 — write the file. Path: doc/adr/<NNNN>-<short-slug>.md. Slug: kebab-case, ≤6 words. Status: proposed. Date: today, ISO format. Deciders: ask the user.
Stop after writing. Do NOT flip status to accepted — that requires user review.
<output_contract>
A single new file at doc/adr/<NNNN>-<short-slug>.md. Status proposed. No existing ADRs modified. No invented content.
ADRs are decision-record artifacts and are exempt from the no-dates rule (Documentation Discipline §2): **Status:** and **Date:** are required for Nygard supersession ordering. Remaining Documentation Discipline rules (WORKFLOW.md §2) apply at write time:
- No emoji anywhere in the file.
Context is the business-context-first section — forces and problem before the decision.- One scope: one decision per ADR.
- No speculation.
Decision is a directive; rejected paths go in Alternatives Considered.
</output_contract>
Next
- Continue the work the ADR was scoped to support. Status starts
proposed; the user flips to accepted after review (the agent does not).
- If the ADR touches
ARCHITECTURE.md's Active ADRs list, add the entry there.
/ad-task for the work units that implement the decision./ad-drift periodically to confirm the decision still holds against the code.
