write-adr
/write-adr
Use when a ticket, plan, or delivery involves a decision with lasting consequences — a library choice, a data model, a boundary between services, a protocol, a deliberate trade-off — and it must be recorded as an Architecture Decision Record others can find and challenge. Invoke for "write an ADR", "document why we chose X", when a decision is escalated via request_decision and resolved, or when you find yourself explaining a non-obvious choice in a commit message.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when a ticket, plan, or delivery involves a decision with lasting consequences — a library choice, a data model, a boundary between services, a protocol, a deliberate trade-off — and it must be recorded as an Architecture Decision Record others can find and challenge. Invoke for "write an ADR", "document why we chose X", when a decision is escalated via request_decision and resolved, or when you find yourself explaining a non-obvious choice in a commit message.
Triggers from the description
Original author description
Use when a ticket, plan, or delivery involves a decision with lasting consequences — a library choice, a data model, a boundary between services, a protocol, a deliberate trade-off — and it must be recorded as an Architecture Decision Record others can find and challenge. Invoke for "write an ADR", "document why we chose X", when a decision is escalated via request_decision and resolved, or when you find yourself explaining a non-obvious choice in a commit message.
How it works
- Template
- Procedure
- Done when
- Review checklist (concrete defects only)
- Capture lore
SKILL.md preview
---
name: write-adr
description: Use when a ticket, plan, or delivery involves a decision with lasting consequences — a library choice, a data model, a boundary between services, a protocol, a deliberate trade-off — and it must be recorded as an Architecture Decision Record others can find and challenge. Invoke for "write an ADR", "document why we chose X", when a decision is escalated via request_decision and resolved, or when you find yourself explaining a non-obvious choice in a commit message.
stack: []
area: docs
---
# Write an Architecture Decision Record
An ADR records one architecturally significant decision in Michael Nygard's format — Title,
Status, Context, Decision, Consequences — so a future reader can see why, judge whether the
reasons still hold, and supersede it deliberately. Keep it to one or two pages, dated,
numbered, and immutable once accepted.
## Template
```markdown
# NNNN. <Imperative decision, e.g. "Use SQLite as the control-plane store">
Date: YYYY-MM-DD
Status: Proposed | Accepted | Rejected | Deprecated | Superseded by [NNNN](NNNN-slug.md)
## Context
The forces: requirements, constraints, what hurt, what is uncertain. Facts, not advocacy.
## Options considered
- **<Option A>** — why it lost, concretely.
- **<Option B>** — why it lost.
## Decision
We will <do X>. <Scope: where it applies and where it does not.>
## Consequences
Easier: … Harder: … Now forbidden: … Revisit if: <measurable trigger>.
```
"Options considered" extends Nygard's format; keep it unless the repo's template
omits it.
## Procedure
When you cannot write files (planning and spec roles), do not draft the file: put the
decision and its options in your output instead, as a ticket or acceptance criterion in
a plan or a `decision` clause in a spec, so a delivery ticket writes the ADR.
1. **Find the convention.** Look for `docs/adr/`, `docs/decisions/`, `doc/adr/`,
`architecture/decisions`, or a numbered `NNNN-title.md` series; match its template,
numbering, and status vocabulary. If none exists, create
`docs/adr/0001-record-architecture-decisions.md` (the convention itself) and write yours
as `0002-…`. Numbers are sequential and never reused. `search_lore` for decisions
already recorded so you neither duplicate nor silently contradict one.
2. **One decision, one sentence.** The title is the decision in the imperative. If you need
"and", write two ADRs.
3. **Context honestly.** Enough that a reader in a year understands why the question arose:
the requirement, constraint or incident that forced it, with links to the ticket or
spec. Include the non-functional forces that actually mattered (consistency under
concurrent writers, durability of acknowledged writes, operability, cost).
4. **Options actually weighed**, each with the concrete reason it lost. "Considered
Postgres; rejected because the factory must run with zero services on a laptop" is
useful; "considered alternatives" is not. Include "do nothing" when it was viable.
5. **Decision in active voice** ("We will…"), with its scope.
6. **Consequences — all of them.** What becomes easier, what becomes harder, what is now
forbidden, new risks and how they are mitigated, and a measurable revisit trigger. This
is the most valuable section and the most often skipped.
7. **Set status truthfully.** An agent-made choice within the ticket's authority may be
`Accepted` and is flagged with `request_decision` at `log_only`/`agent_can_choose`. A
product, architecture or security call you cannot make is `Proposed` and escalated with
`request_decision` as `human_required`; do not mark it accepted yourself. To change an
accepted decision, write a new ADR that says "Supersedes NNNN" and change only the old
one's status line to "Superseded by …".
8. **Link both ways.** Reference the ADR from where the decision bites (module header
comment, README section, config file) and from the ADR index if the repo keeps one.
9. **Mirror into memory and evidence.** Call `suggest_lore` with kind `decision`
summarising the choice and reason, citing the ADR path in the body (the `source`
field takes only a URL). Evidence the file with the `record-evidence` skill, then
stop.
## Done when
- The file is in the repo's ADR directory with the next free number, the date, and a status.
- Context, options (each with its rejection reason), decision and consequences (including
what gets harder and a revisit trigger) are present.
- Links exist from the governed code/doc to the ADR; a superseded ADR's status is updated.
- Formatting passes the repo's markdown check if configured (e.g. `npx --no -- prettier --check`).
## Review checklist (concrete defects only)
- More than one decision in one record, or a title that is a topic, not a decision.
- An option listed without why it lost; consequences with no downside.
- An accepted ADR's body edited instead of superseded; a reused number.
- `Accepted` status on a decision that needed human sign-off.
- The ADR contradicts an existing ADR or lore decision without superseding it.
## Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
**While writing the record you make a lasting decision explicit — the options weighed and why one won — which is exactly the knowledge later agents need before they contradict it.** That kind of fact is *lore*. Capture it via the **lore-capture
protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):
call the Memory MCP `suggest_lore` once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · tmj-90/gaffer | 100 | Apache-2.0 |
| j0hanz/j0hanz-marketplace | 100 | MIT |
| daniel-kindl/dkstack | 100 | MIT |
| existential-birds/beagle | 100 | Apache-2.0 |
| Zeeshan138063/spec-driven-kit | 90 | MIT |
| seancabalse/agentic-playbook | 86 | MIT |
Database snapshot: 13.11.2026 · package version 2ac769a5c753 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 80cmk:adr
Use when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database,… - 100adr
Record a technical decision as an Architecture Decision Record. Use when weighing a framework, library, database, or schema-migration trade-off, or when asked for an ADR. - 87adr
Record one or more Architecture Decision Records from the current conversation. Trigger whenever the user wants to capture, record, log, or write down a decision, an architectural choice, or "the call we just made" — e.g. "record this decision", "let's ADR this", "capture this… - 86adr
Record an architecture decision as a short ADR in docs/adr and index it in docs/ARCHITECTURE.md. Use when a significant technical choice is made (state management, module boundaries, persistence, audio pipeline, a new shared pattern) or when the user asks to record or document a decision. - 100architecture-decisions
Use when a significant technical decision needs to be recorded. Produces Architecture Decision Records that capture context, options, the decision, and its consequences — so the reasoning survives the people who made it. Trigger on "write an adr for this", "document why we chose… - 100architecture-decision-record
This skill should be used when the user is making or documenting a technical or architecture decision: "write an ADR", "document this decision", "should we use X or Y", "compare options for", "design decision", "trade-off analysis", "architecture options", or when a design…