Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Capture an Architecture Decision Record documenting context, reasoning, alternatives, and consequences of a significant technical decision.
category
meta
triggers
["architecture decision","record decision","document decision","adr","why did we choose","design rationale"]
ADR
Purpose: Capture Architecture Decision Records documenting the reasoning behind significant technical choices
Usage:/adr [title] or /adr --from-todo <todo-file>
Iron Laws
CAPTURE THE WHY — The decision itself is visible in code. The ADR exists to record why this choice was made and what alternatives were rejected.
ONE DECISION PER ADR — Each ADR covers a single decision. Split compound decisions into separate records.
CURRENT STATE ONLY — ADRs reflect the current state of thinking. When a decision is superseded, update the status and link to the replacement. Git history tracks the evolution.
Prerequisites
Requires .ai-project/decisions/ directory (created by /init). If it does not exist, create it.
When to Create
Choosing between significant architectural approaches
Adopting a new pattern, library, or technology
Making decisions that affect many files or components
Establishing conventions for the project
Completing a planned work item that involved design choices
Any ADR that references the topic domain should be noted in the "Related Decisions" section of the new ADR, with a brief note about whether it needs updating as a consequence.
If the decision is trivial or forced (see "When NOT to Create"): Suggest skipping the ADR and explain why:
Forced decision (e.g., security patch with no alternatives) — not worth recording
Trivial implementation detail — too granular for an ADR
Already documented — point to existing ADR
Step 2: Assess Scope
Scope
Characteristics
ADR Depth
Local
Affects 1-2 files, single module
Brief — context + decision + key consequence
Cross-cutting
Affects multiple modules, 3-10 files
Standard — full template with alternatives
Architectural
Affects project structure, conventions, or data model
Comprehensive — full template + migration notes + diagrams
Name after the decision topic, not the date: api-client-pattern.md, state-management.md
When superseding: Create a NEW file with a descriptive name for the new decision (e.g., jwt-authentication.md). Do NOT reuse the old ADR's filename — even though git history preserves the old content, having two distinct files makes the superseding relationship explicit and both decisions discoverable.
Template:
# ADR: {Title}**Date:** {YYYY-MM-DD}
**Status:** Accepted
## Context
[What problem or need prompted this decision? What constraints existed?
Include relevant technical context — the reader should understand the situation
without needing to look at other documents.]
## Decision
[What was decided? Be specific about the approach, pattern, or technology chosen.
Include code examples if they clarify the decision.]
## Consequences### Positive- [Concrete benefit with explanation]
### Negative- [Concrete drawback with explanation]
### Migration- [What needs to change to adopt this decision, if anything]
- [Files affected, patterns to update, data to migrate]
## Alternatives Considered### {Alternative 1}-**Approach:** [Brief description]
-**Pros:** [Why it was attractive]
-**Cons:** [Why it was rejected]
### {Alternative 2}-**Approach:** [Brief description]
-**Pros:** [Why it was attractive]
-**Cons:** [Why it was rejected]
For Architectural scope, also include:
## Migration Plan
| Phase | Action | Files Affected |
|-------|--------|----------------|
| 1 | [First step] | [files] |
| 2 | [Second step] | [files] |
## Related Decisions- [Link to related ADRs if they exist]
Step 4: Verify Quality
Before presenting, check:
Context explains the situation without requiring external documents
Decision is specific and actionable (not vague)
At least one alternative was genuinely considered
Consequences include both positive and negative
Migration section addresses what changes (if applicable)
Step 5: Confirm
ADR written to `.ai-project/decisions/{name}.md`**Review the ADR?** (looks good / edit / cancel)
ADR Lifecycle
Status
Meaning
Accepted
Decision is current and active
Deprecated
No longer recommended but still exists in codebase
Superseded
Replaced by a newer ADR (link to replacement)
When superseding an ADR:
Create a NEW ADR file with a descriptive name for the new decision
Update the old ADR's status to Superseded by [new-adr-name.md]
The new ADR's context should reference the previous decision so it stands alone
Both files remain in .ai-project/decisions/ — the old content is preserved in place, not just in git history
Creating from a Completed Todo
When invoked with --from-todo, the workflow adapts:
Read the todo file for context (description, shortcut taken, proper solution, affected files)
The "Context" section incorporates the original problem and constraints from the todo
The "Decision" section captures what was actually implemented
The "Alternatives" section draws from the todo's context about shortcuts vs. proper solutions
After the ADR is created, delete the todo file — the ADR now holds the decision record, git history preserves the todo's existence
Acceptance Tests
ID
Type
Prompt / Condition
Expected
ADR-T1
Positive
"Record why we chose React over Vue"
Skill triggers
ADR-T2
Positive
"Create an ADR for the API pattern"
Skill triggers
ADR-T3
Positive
"Document the architecture decision"
Skill triggers
ADR-T4
Negative
"How does the API work?"
Does NOT trigger (-> /explore)
ADR-T5
Negative
"Add documentation to the codebase"
Does NOT trigger (-> /docs)
ADR-T6
Negative
"Note this tech debt for later"
Does NOT trigger (-> /add-todo)
ADR-T7
Boundary
"Why did we choose this approach?"
Context-dependent — if asking about an existing decision, route to /explore; if recording a new decision, trigger /adr
ADR-T8
Positive
/adr when existing ADR will be superseded
Agent reads existing ADRs, detects superseding relationship, creates new file (does NOT reuse old filename), updates old ADR status
ADR-T9
Boundary
/adr for a trivial formatting decision
Agent suggests skipping — too granular for an ADR per "When NOT to Create"
ADR-T10
Boundary
/adr for a forced security patch
Agent suggests skipping — forced decision with no real alternatives
