Skip to content
Skills Library
Programming · Writing

write-adr

/write-adr

Use when you make a decision that is durable or hard to reverse, such as a framework, data store or public contract. Creates an Architecture Decision Record.

Repository
dkstack ↗
Licence
MIT
Last repository change
11.11.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
1
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

Use when you make a decision that is durable or hard to reverse, such as a framework, data store or public contract. Creates an Architecture Decision Record.

Original author description

Use when you make a decision that is durable or hard to reverse, such as a framework, data store or public contract. Creates an Architecture Decision Record.

How it works

  1. Steps
  2. Subagents
  3. Rules
Original SKILL.md headings · 39 lines, 305 words
SKILL.md preview
---
name: write-adr
description: "Use when you make a decision that is durable or hard to reverse, such as a framework, data store or public contract. Creates an Architecture Decision Record."
---

# Write ADR

Use when a design decision is durable or hard to reverse.

Create an Architecture Decision Record using [architecture/adrs.md](https://raw.githubusercontent.com/daniel-kindl/dkstack/v1/architecture/adrs.md).

## Steps

1. Confirm the decision is worth recording (affects multiple components or is costly to change).
2. Write a short ADR with:
   - Context
   - Options considered
   - Decision
   - Consequences
3. Store it with the code it affects.
4. Do not rewrite old ADRs. Add a new one if the decision changes.

## Subagents

If you can start subagents, use them to research the options. Do step 1 yourself. Then research each option for the "Options considered" section at the same time, each option in its own subagent. Give each subagent a brief that is complete without your context:

- The decision and its context.
- The one option that it researches, and the names of the other options.
- The constraints that you know, for example the components that the decision affects.
- What to report: what the option does, its advantages, its disadvantages and its cost to reverse. Each claim has a source, for example a file path or a link.
- A word limit, for example 300 words.
- This line: "Report to me only. Do not write the ADR, post, approve or merge."

Then collect the reports. Write the ADR yourself in step 2, and do steps 3 and 4 yourself. A report from a subagent is a claim. Check each claim that the decision depends on at its source. If a claim has no source, do not put it in the ADR.

If you cannot start subagents, do the steps one at a time in the order of this skill. Research one option fully before you start the next option.

## Rules

- Keep it short.
- State trade-offs.
- Link related principles from architecture/ when useful.

Versions

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

Database snapshot: 13.11.2026 · package version cd91dc073882 (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
    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.
  • 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
    Write or update an architecture decision record in docs/decisions/ — numbering, front matter, superseding rules and the index. Use whenever a change makes or changes a decision (architecture, public API, infrastructure, security model), and when asked to record, supersede or amend an ADR.
  • 100secondbrain-adr
    This skill should be used when the user asks to "create ADR", "document decision", "architecture decision", "add decision record", or mentions needing to record a technical decision with status tracking and category organization.
  • 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.