write-adr

Writes architecture decision records through structured interviews, git branches, and independent review.

Updated Aug 7, 2026
One-click install
npx skills add https://github.com/sagittaras/agentic-workflow --skill write-adr-sagittaras
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: write-adr
Source: https://github.com/sagittaras/agentic-workflow/tree/main/skills/write-adr
Command: npx skills add https://github.com/sagittaras/agentic-workflow --skill write-adr-sagittaras

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Architectural decisions often get lost or made without documented reasoning, leaving future developers unable to understand why code was written a certain way. This Skill captures decisions in a durable ADR log with full context, alternatives, and trade-offs. ## Core Features & Use Cases - Guided Interview: Conducts a structured interview that refuses to leave questions unanswered or unacknowledged, extracting the problem, constraints, alternatives, and costs before writing anything. - Three Operating Modes: Creates new ADRs, resolves open questions in accepted ADRs, or supersedes prior decisions with proper status transitions. - Automated Git Workflow: Delegates branch creation, commits, and pull requests to shared skills, then runs an independent review via a clean-context subagent before marking the ADR accepted. - Use Case: When deciding to introduce a custom abstraction layer over a library, invoke this Skill to interview stakeholders, document the decision and rejected alternatives, open a PR, and get it independently reviewed. ## Quick Start Ask the assistant to write an ADR for the decision to replace the current logging library with a structured logging framework.

Frequently Asked Questions about write-adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an architecture decision record with Claude Code?

Invoke the write-adr skill with an optional ADR number and decision topic. It interviews you about the problem, alternatives, and costs, then writes the document following your project's ADR conventions and template.

What is an ADR and when should I create one?

An ADR is a durable record of an architectural decision including context, alternatives, and consequences. Create one only for endangered decisions that someone without context might later try to simplify or revert, not for routine library choices.

Can write-adr update an existing accepted ADR?

Yes, it supports resolving open questions within an accepted ADR by editing the same document while keeping its status. Changing an already-given answer requires creating a new ADR that supersedes the original.

Does write-adr merge the pull request automatically?

No, merging is explicitly left to a human. The skill creates the branch and PR, runs independent review rounds until approval, sets the status to accepted, and stops there.

What happens if the interview cannot be completed?

If user answers are unavailable, the skill refuses to write the ADR and instead summarizes what still needs answering. It never invents decision content on the user's behalf.