adr-writer
ADR Writer helps teams document architectural decisions in a structured, numbered format that captures context, alternatives considered, and consequences. It guides you through identifying decision-worthy choices, articulating constraints, evaluating options, and projecting impacts—ensuring future readers understand not just what was decided, but why.
ADR Writer generates structured architecture decision records that capture context, rationale, alternatives, and consequences in numbered format.
AI-generated summary based on this skill's SKILL.md
Install
Mathews-Tom/armory/adr-writer · repository language: Python
git clone https://github.com/Mathews-Tom/armory
cp -r armory/skills/adr-writer ~/.claude/skills/adr-writernpx skillfed install Mathews-Tom/armory/adr-writerFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What is adr-writer and what does it help me do?
adr-writer helps teams document architectural decisions in a structured, numbered format that captures context, alternatives considered, and consequences. It guides you through identifying decision-worthy choices, articulating constraints, evaluating options, and projecting impacts—ensuring future readers understand not just what was decided, but why.
How do I document design decisions using adr-writer?
adr-writer walks you through a structured process: identify the decision and its context, list constraints and assumptions, enumerate alternatives with tradeoffs, state your chosen option, and document consequences. The tool generates a numbered record with metadata and optional links to superseded prior decisions, creating an audit trail of your reasoning.
Can adr-writer capture architecture decision with context and alternatives?
Yes. adr-writer is designed to capture architecture decisions with full context, enumerate alternatives you considered, and document the tradeoffs between them. It structures this information so the decision rationale is preserved for future reference, helping teams understand constraints and rejected options alongside the final choice.
What format does adr-writer use for decision records?
adr-writer generates numbered, status-tracked architecture decision records with proper metadata. Each record includes sections for context, alternatives, consequences, and decision rationale. The tool supports supersession links to existing decisions, establishing a governance and audit trail for your system design choices.
Why should my team use adr-writer to document architectural choices?
adr-writer ensures your architectural reasoning is preserved for future reference and team onboarding. By capturing context, tradeoffs, and rejected alternatives in a structured format, it prevents knowledge loss, enables informed re-evaluation of past decisions, and establishes accountability and governance around critical design choices.
Does adr-writer support metadata and links between decisions?
Yes. adr-writer creates ADRs with proper metadata and supersession links to existing decisions. This allows you to track how architectural choices evolve over time, understand which prior decisions a new one replaces, and maintain a connected, auditable history of your system's design evolution.
SKILL.md
rendered from the published skill — quoted content, verbatim
ADR Writer
Captures architecture decisions in a lightweight, structured format that preserves context, rationale, alternatives, and consequences. Produces numbered ADR documents with proper status lifecycle — preventing the "why did we do it this way?" problem when revisiting decisions months later.
Reference Files
| File | Contents | Load When |
|---|---|---|
references/adr-template.md |
Standard ADR template with field explanations and examples | Always |
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 6 files
skills/adr-writer/SKILL.md
skills/adr-writer/evals/cases.yaml
skills/adr-writer/references/adr-template.md
skills/adr-writer/references/alternatives-analysis.md
skills/adr-writer/references/context-capture.md
skills/adr-writer/references/status-lifecycle.md