adr-writer
ADR Writer creates formatted architecture decision records that capture the problem, alternatives weighed, and chosen solution. It automatically numbers files, slugifies titles, and populates a standard template to ensure design decisions survive team turnover.
ADR Writer generates architecture decision records from your context, options, and chosen path.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-06-30
ADR Writer generates architecture decision records from your context, options, and chosen path. ADR Writer creates formatted architecture decision records that capture the problem, alternatives weighed, and chosen solution. It automatically numbers files, slugifies titles, and populates a standard template to ensure design decisions survive team turnover.
Use it when
- ADR Writer uses a structured template that captures the essential elements of architectural choices: context (the problem and constraints).
- Yes.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
oxbshw/LLM-Agents-Ecosystem-Handbook/adr-writer · repository language: Python
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write an ADR with adr-writer?
ADR Writer guides you through creating formatted architecture decision records by automatically numbering files, slugifying titles, and populating a standard template. You provide the problem context, alternatives considered, and your chosen solution; adr-writer structures it into a complete ADR file that preserves your architectural reasoning for future teams.
What is an architecture decision record template?
ADR Writer uses a structured template that captures the essential elements of architectural choices: context (the problem and constraints), decision (what you chose and why), consequences (trade-offs and implications), and alternatives (options you rejected). This format ensures design decisions are documented consistently and remain understandable long after the original decision-makers leave.
Can adr-writer automatically generate ADR files?
Yes. ADR Writer automatically generates ADR files by handling file numbering (adr-nnnn format), slugifying your decision title into the filename, and populating the standard template sections. You focus on capturing the decision details; adr-writer handles the formatting and file structure to preserve architectural choices systematically.
How does adr-writer capture design decisions before knowledge is lost?
ADR Writer combats institutional knowledge loss by converting informal architectural discussions into permanent, structured records. By automating the ADR format and making documentation frictionless, it ensures design rationale is captured and accessible before team turnover occurs, protecting your architecture's reasoning from being lost.
What format does adr-writer use for decision records?
ADR Writer generates markdown files following the adr-nnnn naming convention, where nnnn is an auto-incremented number. Each record includes sections for status, context, decision, consequences, and alternatives—a proven format that makes architectural choices discoverable and their trade-offs transparent to current and future teams.
Is adr-writer open source?
Yes, adr-writer is released under the MIT license, making it free to use, modify, and distribute. This open-source approach encourages teams to adopt structured architecture decision documentation and contribute improvements to the tool.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
ADR Writer
When to use
- A non-trivial architecture decision was just made
- Reverse-documenting a decision that wasn't recorded but should have been
- Preparing for a design review
When NOT to use
- Trivial choices (naming, formatting)
- Operational runbooks (those go to
runbooks/) - Product decisions without architectural impact
Inputs
| Name | Type | Required | Notes |
|---|---|---|---|
context |
string | yes | The problem being solved, in 2–4 sentences |
options |
list | yes | Alternatives considered |
decision |
string | yes | Chosen path |
number |
int | no | If omitted, finds next ADR number from memory/decisions/ |
Outputs
A file at memory/decisions/ADR-NNNN-<slug>.md matching the ADR template.
Workflow
- Find the next ADR number (or use
numberinput) - Slugify the decision's main subject
- Fill the template:
- Context,
(truncated - see the full file via the links below)
File tree — 1 file
skills/catalog/adr-writer/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Document an architecture decision in ADR format with context, options, and rationale”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
ADR Writer guides you through building comprehensive Architecture Decision Records that capture the reasoning behind key technical choices. It provides a structured template covering context, decision rationale, alternatives evaluated, tradeoffs made, and consequences—helping teams document and communicate architecture decisions clearly.
Adr helps you systematically capture architecture decisions with context, options, and consequences. Create numbered decision records, browse your decision history, and search past choices to avoid redundant deliberation.
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 guides you through documenting architectural decisions by establishing the problem context, weighing real alternatives, explaining why one direction won, and recording both benefits and costs. It enforces boundaries between decision rationale and product obligations, keeping ADRs focused on justification rather than execution or RFC-level commitments.
This skill walks you through the complete ADR lifecycle—from evaluating whether a decision is ready to record, through structured creation using the MADR template, to quality checks and ongoing log management. It grounds decisions in proven frameworks like START (readiness criteria) and ECADR (completion criteria), helping teams capture architectural rationale rather than just outcomes.
Create and maintain Architecture Decision Records that capture the reasoning behind significant technical choices. This skill provides multiple templates—from standard MADR format to lightweight Y-statements—and guidance on when ADRs matter most, helping teams establish clear decision-making processes and onboard members through documented architectural history.