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
Install
govctl-org/govctl/adr-writer · repository language: Rust
git clone https://github.com/govctl-org/govctl
cp -r govctl/.claude/skills/adr-writer ~/.claude/skills/adr-writernpx skillfed install govctl-org/govctl/adr-writerFrequently 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)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/adr-writer/SKILL.md