michelve This skill uses extended thinking for complex architectural trade-off analysis. ultrathink
ADR Writer
Writes complete, validated Architecture Decision Records in MADR 4.0.0 format and commits them to docs/decisions/. Follow write-adr.prompt.md for the full 10-step workflow.
When to Activate
Activate on:
- "write an ADR for X"
- "create an ADR"
- "document this decision"
- "ADR for X"
- "architecture decision record for X"
- "record this decision"
- "document the decision to use X"
- "we decided to use X, write that up"
- Invoked from
check-adr-violations.prompt.mdwith asupersedes: NNNNparameter
Do NOT activate on:
- "what ADR covers X?" → lookup task, read the index
- "show me the ADR for Y" → lookup task, read the file
- "does this violate an ADR?" → audit task, use
check-adr-violations.prompt.md - "check ADR compliance" → audit task, use
check-adr-violations.prompt.md
MADR 4.0.0 - Mandatory Sections
Every ADR must contain all five mandatory sections. Missing any>
| Section | Required | Notes |
|---|---|---|
| YAML frontmatter | ✅ | status + date always present |
| Context and Problem Statement | ✅ | 2–4 sentences, factual, project-specific |
| Considered Options | ✅ | 2–4 options, concise noun phrases |
| Decision Outcome | ✅ | Must start with Chosen option: "X", because |
| Consequences | ✅ | At least one Good + one Bad bullet |
Phrasing Rules (non-negotiable)
Decision Outcome - exact format:
Chosen option: "{option name}", because {justification}.
Consequences bullets - exact format:
- Good, because {positive consequence}.
- Bad, because {negative consequence}.
- Neutral, because {neutral consequence}.
Numbering Convention
- Read
docs/decisions/README.md- find highestNNNN - Increment by 1
- Filename:
NNNN-short-title.md(lowercase kebab-case, max 5 words) - Always update the index table in
docs/decisions/README.mdafter writing the file
Status Values
| Status | When to use |
|---|---|
accepted |
Decision is made and implemented (most common) |
proposed |
Decision under discussion, not yet implemented |
superseded |
Replaced by a newer ADR - add superseded-by: NNNN - Title |
deprecated |
No longer relevant, not replaced |
Supersede Flow
When replacing an existing ADR (triggered by violation checker or user intent):
- New ADR frontmatter gets
supersedes: "NNNN - Old Title" - Old ADR frontmatter changes to
status: superseded+superseded-by: "NNNN - New Title" - Old ADR row in
docs/decisions/README.mdstatus column →superseded - New ADR row added to index as
accepted
Optional: Web Research
If the user asks for external evidence or benchmarks to support the decision, invoke the web-research-specialist agent before finalizing. Use its findings in the Consequences section or a More Information section.
Arguments
When invoked with the supersedes: NNNN argument (either by user or from check-adr-violations.prompt.md), the $ARGUMENTS variable contains the ADR number to supersede.
Example invocation: /adr-writer supersedes: 0005
The argument is parsed to:
- Mark the old ADR (0005) as
status: superseded - Add
supersedes: "0005 - Old Title"to the new ADR frontmatter - Update the index table in README.md to reflect the supersession
If no arguments are provided, this is a new ADR with no supersession relationship.
Session Tracking
This skill logs the session ID using ${CLAUDE_SESSION_ID} for correlation:
ADR creation session: ${CLAUDE_SESSION_ID}
This allows tracking which ADRs were written in the same conversation and correlating with git commits when troubleshooting.
Action
Invoke .github/prompts/write-adr.prompt.md and follow its steps in order. Do not shortcut or skip the validation step.