Skip to content
Skills Library
Programming · Writing

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).

Licence
MIT
Last repository change
27.10.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 27.10.2026, without references to retired models or APIs.

Licence

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

  1. Rules
  2. Referencing
  3. Template
Original SKILL.md headings · 68 lines, 452 words
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

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

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.

Feedback and reports

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