Skip to content
Skills Library
Programming · Writing

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.

Repository
gaffer ↗
Licence
Apache-2.0
Last repository change
29.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.09.2026, without references to retired models or APIs.

Licence

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

write an ADRdocument why we chose X
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

  1. Template
  2. Procedure
  3. Done when
  4. Review checklist (concrete defects only)
  5. Capture lore
Original SKILL.md headings · 95 lines, 784 words
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

RepositoryScoreLicence
This page · tmj-90/gaffer100Apache-2.0
j0hanz/j0hanz-marketplace100MIT
daniel-kindl/dkstack100MIT
existential-birds/beagle100Apache-2.0
Zeeshan138063/spec-driven-kit90MIT
seancabalse/agentic-playbook86MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.