Produce one ADR per invocation. An ADR records a decision that has already
been made; if the decision is still open, use /create-rfc. Follow the
five-step process — do not skip Step 2 (validate mandatory fields) or draft
before every mandatory field is present.
Hard rules
- Never invent facts. If a mandatory field is missing, ask. Never fill Context, Decision, or Consequences with plausible-sounding filler.
- Never edit an existing ADR to change the decision. Supersede with a new ADR and link back. ADRs are historical records.
- Never skip trade-offs. Consequences must be honest — include what becomes harder, not just what becomes easier.
- Never write in a language other than the user's. Match the language the user is using in this session.
Dispatch
Run the process in order. Read the matching reference file fully before acting — it is the playbook for that step.
| Step | Read | Purpose |
|---|---|---|
| 1 — Gather context | references/process.md |
Ask for decision, format, status, supersedes |
| 2 — Validate mandatory fields | references/process.md |
Ensure title, date, status, context, decision, consequences are present |
| 3 — Pick format | references/formats.md |
MADR (default) / Nygard / Y-Statement |
| 4 — Assign number | references/numbering.md |
Scan directory, assign next sequential number |
| 5 — Generate + place | references/process.md + one of templates/adr-{madr,nygard,y-statement}.md |
Fill template, run quality checklist, confirm file location |
Run the quality checklist (references/quality.md) before finalizing —
titles, honest trade-offs, options actually compared, naming convention.
Templates
Pure markdown scaffolds; load only the one for the chosen format:
| Format | Template |
|---|---|
| MADR (default) | templates/adr-madr.md |
| Nygard | templates/adr-nygard.md |
| Y-Statement | templates/adr-y-statement.md |
Universal rules
- Honesty. Record trade-offs, unknowns, and open questions honestly.
Never cover a gap with an invented answer. If a field cannot be filled,
ask or leave an italicized placeholder (
*to be confirmed*). - Immutability. ADRs are historical records. Never edit the decision
after the fact — supersede with a new ADR and link
Superseded by ADR-{NNN}on the old one. - Short is better. 200–500 words is ideal. If longer, move detail to a linked design doc or RFC.
- Date everything. What seems obvious now will not be in three years.
- Language adaptation. Always write the ADR in the user's language.
- Confirm before writing. Suggest the file path in Step 5; write only after the user confirms placement.
Sibling skills
Reach for these at any point in the flow:
/create-rfc— the decision has not been made yet. Use RFC to propose options, gather feedback, and drive alignment. Once the decision is made, come back to/create-adrto record it./forge— spec-driven implementation. Use/forge specify | design | plan | executewhen the ADR is decided and you need to build the thing. An ADR often lands as a link in a forgedesign.md.
Attribution
Based on create-adr by Tech Leads Club, licensed under CC-BY-4.0. Changes have been made to the original.