Skip to content
Skills Library
Programming · Writing

write-adr

/write-adr

Write an architecture decision record for a choice that is hard to reverse. Use when you choose a stack, a vendor, a data model or a protocol.

Licence
MIT
Last repository change
11.11.2026

Assessment and security

86/ 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.
Content21 / 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 11.11.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

Write an architecture decision record for a choice that is hard to reverse. Use when you choose a stack, a vendor, a data model or a protocol.

Arguments

/write-adr [the decision to make]
Original author description

Write an architecture decision record for a choice that is hard to reverse. Use when you choose a stack, a vendor, a data model or a protocol.

How it works

SKILL.md has no level-two headings · 19 lines, 237 words

SKILL.md preview
---
name: write-adr
description: "Write an architecture decision record for a choice that is hard to reverse. Use when you choose a stack, a vendor, a data model or a protocol."
argument-hint: "[the decision to make]"
---

# Write an ADR

> Playbook files named here: when the project has its own copy at `.playbook/local/<same path>`, use that copy instead.

Decision: $ARGUMENTS

1. **Check it needs an ADR** (`${CLAUDE_PLUGIN_ROOT}/principles/03-adrs-and-decisions.md`). If it's easy to reverse, log it in the Decision Log instead (`log-decision`).
2. **Read what exists**: `docs/adr/` (the next number, related ADRs, ones this supersedes), the Decision Log, and the PRD requirements involved.
3. **Gather the forces**: requirements with ids, constraints (platform, budget and free tiers, team, compliance), and what's already decided.
4. **Find at least two real options.** For each, check the current docs and versions (not memory): maturity, adoption, licence, cost, lock-in, and fit with the stack. If the answer depends on numbers you don't have (performance, memory, cost), propose a **time-boxed spike** with what it will measure, and stop there.
5. **Ask the owner** when the choice is a product or business trade-off: present the options with your recommendation first. Technical choices with a clear winner: recommend, and let the owner confirm in review.
6. **Write `docs/adr/NNNN-kebab-title.md`** from `${CLAUDE_PLUGIN_ROOT}/templates/adr.md`. Status is Proposed until the owner accepts it; then Accepted with the date and who decided.
7. **Follow through**:
   - Add a row to the Decision Log pointing to the ADR.
   - Add the rules it implies to `AGENTS.md`.
   - File tickets for the "now we must" consequences.
   - When superseding, mark the old ADR *Superseded by NNNN* without changing its body.

Versions

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

Database snapshot: 13.11.2026 · package version 27c1ddf62ab9 (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

  • 100adr-writer
    Write or supersede an architecture decision record (ADR). Use to record a hard-to-reverse decision.
  • 100adr-writer
    Write an Architecture Decision Record (ADR) as a Markdown file. Use when the user asks to create, draft, document or record an architecture/technical decision, or mentions "ADR", "decision record" or "registro de decisión de arquitectura".
  • 100adr
    Writes or reviews an Architecture Decision Record (context, drivers, options, decision, consequences) stored per service repo. Use for \"write an ADR\", \"document this decision\", or recording why an approach was chosen.
  • 100architecture-decision-records
    Record a hard-to-reverse decision for TS Inspector as a numbered ADR in docs/adr/. Use for licence changes, new vendored programs, new dependencies, output formats, build or hosting changes, or when the user says "record this decision".
  • 90create-adr
    Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest…
  • 90create-adr
    Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest…

Feedback and reports

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