ADR Skill
Capture architectural decisions as they happen, so the why lives next to the code
instead of in a Slack thread or someone's memory. Produces lightweight ADR documents
under docs/adr/.
Keywords
adr, architecture decision record, decision, rationale, trade-off, alternatives, we decided, why did we choose, design decision, supersede, decision log, nygard
When to record a decision
- The user says "record this", "ADR this", "let's document this decision".
- A choice is made between significant alternatives: framework, library, database,
language, pattern, API shape, infra/deploy approach, build vs buy.
- The user says "we decided to…" or "the reason we're doing X instead of Y is…".
- The user asks "why did we choose X?" → read and summarize the existing ADR.
For trivial or easily-reversible choices, don't create an ADR — note it inline and move on.
Output Artifacts
| Request |
Output |
/adr new "<title>" |
A new docs/adr/NNNN-<slug>.md + an updated index |
/adr list |
The decision log (ID, title, status, date) |
/adr supersede <NNNN> |
A new ADR marked as superseding an old one; old one flipped to superseded |
Format
Lightweight Nygard ADR, adapted for AI-assisted work:
# ADR-NNNN: <Decision Title>
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: <who was involved>
## Context
What is the issue motivating this decision? The situation, constraints, and forces at
play. 2–5 sentences.
## Decision
What we are doing. 1–3 sentences, stated clearly.
## Alternatives Considered
### <Alternative>
- **Pros**: …
- **Cons**: …
- **Why not**: the specific reason it was rejected.
(Repeat per alternative.)
## Consequences
### Positive
- …
### Negative / trade-offs
- …
### Risks
- <risk and its mitigation>
NEW — Record a decision
- Initialize once. If
docs/adr/ does not exist, ask the user to confirm before
creating it. On confirmation, create the directory, a README.md seeded with the
index table header (below), and a template.md copy of the format above. Never
create files without explicit consent.
- Number it. Next zero-padded number after the highest existing
docs/adr/NNNN-*.md
(start at 0001). Slug = kebab-case of the title.
- Fill it from the conversation — extract the decision, the context that prompted it,
the alternatives actually weighed, and the consequences. Do not invent alternatives
that were never discussed; if context is thin, ask one or two targeted questions.
- Default status
accepted when the user states a decision; proposed when still
weighing. Date = today.
- Update the index in
docs/adr/README.md.
Index format
docs/adr/README.md:
# Architecture Decision Records
| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-0001](0001-use-eks-over-ecs.md) | Use EKS over ECS | accepted | 2026-06-10 |
SUPERSEDE — Replace a decision
- Read the old ADR.
- Create a new ADR that references it: "Supersedes ADR-NNNN" in Context.
- Flip the old ADR's
Status to superseded by ADR-MMMM.
- Update both rows in the index.
Never delete or rewrite a past ADR's decision — superseding preserves the history of
why it changed, which is the whole point.
1---2name: adr3description: Capture architectural decisions that have already been made, as structured ADRs (Architecture Decision Records). Use when user says 'record this decision', 'ADR this', 'why did we choose X', 'document this trade-off', 'we decided to...', or when a choice between alternatives has been settled and needs writing down. This records a decision; it does not make one. A question of the form 'should we use X or Y' is a design discussion, not an ADR request.4---56# ADR Skill78Capture architectural decisions as they happen, so the *why* lives next to the code9instead of in a Slack thread or someone's memory. Produces lightweight ADR documents10under `docs/adr/`.1112## Keywords13adr, architecture decision record, decision, rationale, trade-off, alternatives, we decided, why did we choose, design decision, supersede, decision log, nygard1415## When to record a decision1617- The user says "record this", "ADR this", "let's document this decision".18- A choice is made between **significant alternatives**: framework, library, database,19 language, pattern, API shape, infra/deploy approach, build vs buy.20- The user says "we decided to…" or "the reason we're doing X instead of Y is…".21- The user asks "why did we choose X?" → read and summarize the existing ADR.2223For trivial or easily-reversible choices, don't create an ADR — note it inline and move on.2425## Output Artifacts2627| Request | Output |28|---------|--------|29| `/adr new "<title>"` | A new `docs/adr/NNNN-<slug>.md` + an updated index |30| `/adr list` | The decision log (ID, title, status, date) |31| `/adr supersede <NNNN>` | A new ADR marked as superseding an old one; old one flipped to `superseded` |3233---3435## Format3637Lightweight Nygard ADR, adapted for AI-assisted work:3839```markdown40# ADR-NNNN: <Decision Title>4142**Date**: YYYY-MM-DD43**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN44**Deciders**: <who was involved>4546## Context4748What is the issue motivating this decision? The situation, constraints, and forces at49play. 2–5 sentences.5051## Decision5253What we are doing. 1–3 sentences, stated clearly.5455## Alternatives Considered5657### <Alternative>58- **Pros**: …59- **Cons**: …60- **Why not**: the specific reason it was rejected.6162(Repeat per alternative.)6364## Consequences6566### Positive67- …6869### Negative / trade-offs70- …7172### Risks73- <risk and its mitigation>74```7576---7778## NEW — Record a decision79801. **Initialize once.** If `docs/adr/` does not exist, ask the user to confirm before81 creating it. On confirmation, create the directory, a `README.md` seeded with the82 index table header (below), and a `template.md` copy of the format above. Never83 create files without explicit consent.842. **Number it.** Next zero-padded number after the highest existing `docs/adr/NNNN-*.md`85 (start at `0001`). Slug = kebab-case of the title.863. **Fill it from the conversation** — extract the decision, the context that prompted it,87 the alternatives actually weighed, and the consequences. Do not invent alternatives88 that were never discussed; if context is thin, ask one or two targeted questions.894. **Default status** `accepted` when the user states a decision; `proposed` when still90 weighing. Date = today.915. **Update the index** in `docs/adr/README.md`.9293## Index format9495`docs/adr/README.md`:9697```markdown98# Architecture Decision Records99100| ID | Title | Status | Date |101|----|-------|--------|------|102| [ADR-0001](0001-use-eks-over-ecs.md) | Use EKS over ECS | accepted | 2026-06-10 |103```104105## SUPERSEDE — Replace a decision1061071. Read the old ADR.1082. Create a new ADR that references it: "Supersedes ADR-NNNN" in Context.1093. Flip the old ADR's `Status` to `superseded by ADR-MMMM`.1104. Update both rows in the index.111112Never delete or rewrite a past ADR's decision — superseding preserves the history of113*why it changed*, which is the whole point.
anmolnagpal