adr-writer
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.
ADR Writer helps you document architectural decisions by capturing context, evaluated alternatives, the chosen direction, and its consequences.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-27
ADR Writer helps you document architectural decisions by capturing context, evaluated alternatives, the chosen direction, and its consequences. 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.
Use it when
- adr-writer structures ADRs around context (the problem you faced), alternatives (real options you considered).
- adr-writer emphasizes recording your decision rationale—the reasoning that led you to select one approach over others.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
govctl-org/govctl/adr-writer · repository language: Rust
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 do I write architecture decision records with adr-writer?
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.
What should an ADR template for design decisions include?
adr-writer structures ADRs around context (the problem you faced), alternatives (real options you considered), and consequences (benefits and costs of your choice). This template ensures you document not just what you decided, but why that decision beat the alternatives and what trade-offs you accepted.
How does adr-writer help document why we chose this architecture?
adr-writer emphasizes recording your decision rationale—the reasoning that led you to select one approach over others. By capturing context and alternatives alongside consequences, it creates a clear record of why a design choice was selected, making it easier for future teams to understand the original thinking.
Can adr-writer audit and review ADR content for completeness?
adr-writer supports governance and quality standards by helping you record architectural decisions with proper structure and depth. It audits content to ensure context, alternatives, and consequences are all present, enforcing completeness so your decision records remain useful for future reference and governance.
How does adr-writer maintain decision history and trace superseded choices?
adr-writer helps you maintain a decision log that records both current and superseded architectural choices. By documenting the full history of why decisions were made and later changed, it lets you trace the evolution of your architecture and understand what trade-offs led to each transition.
What are best practices for writing ADRs with adr-writer?
adr-writer enforces best practices by keeping ADRs focused on justification rather than execution or RFC-level commitments. Document real alternatives you weighed, explain the context that made your choice right, and record both benefits and costs. This keeps decision records clear, traceable, and useful for governance.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
ADR Writer
Record why one design direction was chosen over alternatives, under what constraints, and with what consequences. ADRs justify decisions; they are not mini-RFCs or execution logs.
This helper owns ADR content quality. Use spec or gov for acceptance,
rejection, supersession, or implementation work.
Discovery
Inspect related decisions and requirements before writing:
govctl adr show <ADR-ID>
govctl search <topic>
Use govctl adr --help and subcommand help for current creation and nested-field
editing syntax. Use govctl adr show <ADR-ID> --history when superseded history
matters.
Hard Stops
- Do not accept, reject, or supersede an ADR from this helper.
- Do not create externally visible behavior, validation, lifecycle, storage, or compatibility obligations in ADR prose. Establish them in an RFC.
- Do not store task scope, progress, commands run, validation
(truncated - see the full file via the links below)
File tree — 1 file
.claude/skills/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 › “Write and structure architecture decision records with context, alternatives, and consequences”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Decision Analysis exposes assumptions, failure paths, and success conditions for high-stakes design choices. It uses premortem and backcast reasoning to rank options against constraints, reversibility, and evidence quality, then returns a risk-calibrated recommendation. The skill routes obligations and rationale to their authoritative destinations—RFC, ADR, Work Item, or verification—rather than creating artifacts itself.
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.
discuss guides you through governance design conversations grounded in your repository's existing context. It helps identify constraints, compare design options, and produce durable artifacts like RFCs and ADRs that capture decisions and obligations without moving into implementation.
gov delivers substantive code changes within your repository's governance framework, enforcing RFC and ADR authority while maintaining work-item traceability. It establishes current state, validates against normative specifications, and ensures completion evidence before closure.
migrate helps you add govctl governance to an established project by examining existing evidence—documentation, code structure, VCS history, and configuration—to recover consequential decisions and specifications. It guides you through a discovery phase, presents candidates for backfill as Architecture Decision Records, RFCs, or Work Items, and executes only authorized changes in small coherent batches. The workflow preserves traceability, respects existing artifact state, and stops when evidence conflicts or authorization is unclear.
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.
More skills rfc-writer (MIT) · commit (MIT) · detach (MIT)