write-adr
/write-adr
Record a settled decision as an ADR. Use when the decision will outlive the effort that made it. Not for behavior a change must deliver (write-specs), or decisions not yet settled (grilling).
- Author
- j0hanz ↗
- Repository
- j0hanz-marketplace ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Record a settled decision as an ADR. Use when the decision will outlive the effort that made it. Not for behavior a change must deliver (write-specs), or decisions not yet settled (grilling).
Original author description
Record a settled decision as an ADR. Use when the decision will outlive the effort that made it. Not for behavior a change must deliver (write-specs), or decisions not yet settled (grilling).
How it works
- Rules
- Referencing
- Template
SKILL.md preview
--- name: write-adr description: Record a settled decision as an ADR. Use when the decision will outlive the effort that made it. Not for behavior a change must deliver (write-specs), or decisions not yet settled (grilling). --- # Write ADR An ADR fixes **why the system is shaped this way**, so the next reader argues with the reasoning instead of re-running it. Write one once the decision is settled — [grilling](../grilling/SKILL.md) is where that happens. It earns a record when it constrains work that has not started: a technology, a boundary, a protocol, a convention everything downstream must match. A choice reversible in an afternoon is a code comment. ## Rules One decision per record, titled as the decision rather than its topic — "Issue RS256 JWTs, verified per service", not "Authentication". Each option carries the one line that lost it. Where nothing was rejected, go find what was. Where nothing was, it is not an ADR — write the choice as a code comment at the site it shapes, or, before that code exists, as a line in the governing spec's Constraints ([write-specs](../write-specs/SKILL.md)). Consequences include what got worse. The cost accepted is the one thing a reader cannot reconstruct from the code. An accepted record stays as written — its reasoning stood on facts true that day. Supersede instead: a new record, plus one line on the old one linking it. Done when the record is written to `docs/adr/NNN-<slug>.md` under the next free number, titled as one decision statement, carries at least one rejected option with the line that lost it, states the decision as a commitment, and names the cost accepted in Consequences. (The supersede rule above governs the record's later life and is not part of this check.) ## Referencing Write the record to `docs/adr/NNN-<slug>.md`: `NNN` is the next zero-padded three-digit number after the highest already in `docs/adr/` (`001` when there is none), `<slug>` the decision in a few kebab-case words. It sits outside the per-change directories under `docs/plan/` — a decision outlives the change that made it. Paths are relative **to the record**: ```markdown superseded by [`ADR-012`](012-<slug>.md) existing code [`db.ts:40-60`](../../src/lib/db.ts#L40-L60) spec [`auth spec`](../plan/2026-08-13-auth/auth.spec.md) ``` A spec quotes the record from its Constraints by link ([write-specs](../write-specs/SKILL.md)). ## Template ```markdown # ADR-NNN: <the decision, as a statement> **Status**: accepted, <YYYY-MM-DD> **Deciders**: <who confirmed it> ## Context 2–5 sentences: the forces in play — the constraint, the deadline, the system it has to fit. Facts as they stood, not as they turned out. ## Options - **<option>** — <the one line that lost it> - **<option, chosen>** — <the one line that won it> ## Decision One paragraph, stated as a commitment: "we will …". ## Consequences - <what this makes easy or cheap> - <the cost accepted — what got worse> - <what has to change if it is ever revisited> ``` Superseding touches one line on the old record: ```markdown **Status**: superseded by [ADR-012](012-<slug>.md), <YYYY-MM-DD> ```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · j0hanz/j0hanz-marketplace | 100 | MIT |
| daniel-kindl/dkstack | 100 | MIT |
| tmj-90/gaffer | 100 | Apache-2.0 |
| 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 a25171ae9fe7 (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
- 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… - 100adr
Capture architectural decisions that have already been made, as structured ADRs (Architecture Decision Records). Use when user says 'record this decision', 'ADR this', 'why did we choose X', 'document this trade-off', 'we decided to...', or when a choice between alternatives has… - 100adr-write
Record a single architecture decision as a numbered ADR. Use when the user says "record this as an ADR", "log this decision", "capture this as an ADR", or "create an ADR"; or when another skill has surfaced a decision at the end of a discussion and the user has approved turning… - 100to-adr
Record an Architecture Decision Record (ADR) — 1–3 sentences on what was decided and why. Use when user says "create an ADR", "record this decision", or just made an architecturally significant choice. Don't use for forward-looking specs (/to-spec) or repo conventions (CLAUDE.md). - 100decision-memory
Use when planning, designing, reviewing, or changing code in a repository that keeps ADRs (usually docs/adr) — to load the decisions that already govern the work, check a plan or diff against them, or record a new decision. Also use when a choice feels already-settled and you… - 100adr
Read and write Architecture Decision Records in docs/adr/. Use for /adr, when decisions are made, and before changing areas covered by ADRs.