Skip to content
Skills Library
Programming · Writing

architecture-decision

/architecture-decision

Write an architecture decision record (context, options, decision, consequences) where the project keeps them. Use it when a hard-to-undo choice is made (a framework, database, data model, API style, service split) or the user asks to record or justify a technical decision.

Repository
yaap ↗
Licence
MIT
Last repository change
13.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
0
Deprecation

No signals detected. Repository changed on 13.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 (context, options, decision, consequences) where the project keeps them. Use it when a hard-to-undo choice is made (a framework, database, data model, API style, service split) or the user asks to record or justify a technical decision.

Original author description

Write an architecture decision record (context, options, decision, consequences) where the project keeps them. Use it when a hard-to-undo choice is made (a framework, database, data model, API style, service split) or the user asks to record or justify a technical decision.

How it works

  1. When an ADR is worth it
  2. 1. Find where ADRs live
  3. 2. Gather the context
  4. 3. Weigh real options
  5. 4. Write the decision
  6. 5. Status and changes
  7. In YAAP
  8. Template
Original SKILL.md headings · 97 lines, 652 words
SKILL.md preview
---
name: architecture-decision
description: Write an architecture decision record (context, options, decision, consequences) where the project keeps
  them. Use it when a hard-to-undo choice is made (a framework, database, data model, API style, service split) or the
  user asks to record or justify a technical decision.
license: MIT
metadata:
  sources: wshobson/plugins/documentation-generation/skills/architecture-decision-records,
    agency-agents/engineering/engineering-software-architect.md
---

# Architecture decision

Code shows what was built, not why, and not what was rejected. An ADR keeps the reason, so that a later change can
tell whether the reason still holds instead of guessing or repeating an old debate.

## When an ADR is worth it

Write one when a decision is costly to reverse, affects more than one part of the system, or picks between options
that reasonable people would weigh differently. Skip it for bug fixes, routine upgrades and choices that one small
commit can undo; a line in the commit message is enough there.

## 1. Find where ADRs live

Look for an existing folder: `docs/adr/`, `docs/decisions/`, `adr/`, `architecture/decisions/`. Follow what is there:
its numbering, file names, template and index. When there is none, use `docs/adr/NNNN-short-title.md` with four-digit
numbers starting at `0001`, and a `docs/adr/README.md` that lists them. Ask the user before starting a new folder in
a project that has its own documentation layout.

Read the ADRs that touch the same area. A new decision may supersede one of them, and must say so.

## 2. Gather the context

State the problem without the solution in it. Collect the forces: requirements, constraints (team, budget, time,
existing systems), quality attributes that matter here (latency, cost, safety, simplicity) and what happens if
nothing is decided. Read the code involved; a decision about code you have not read is a guess.

## 3. Weigh real options

List two to four options that could actually be chosen, including "keep what we have" when it is viable. For each,
give the honest pros and cons, and what it costs to reverse later. An option list with one serious candidate and two
straw men tells the reader nothing. Name what is given up, not only what is gained.

When the choice is unclear, say so and ask the user; the ADR records a decision, it does not make it on its own.

## 4. Write the decision

One or two sentences, in active voice: "We store sessions in the database, not in signed cookies." Then the
consequences: what becomes easier, what becomes harder, what must now be done (migrations, follow-up work), and which
risks remain. Negative consequences belong here too; leaving them out is how the same debate comes back.

Keep it to a page or two. Link, do not copy, long designs or benchmarks.

## 5. Status and changes

Statuses: *Proposed* (under discussion), *Accepted*, *Rejected*, *Deprecated*, *Superseded by NNNN*. Once accepted,
an ADR is not rewritten: a new decision gets a new ADR that supersedes it, and the old one only gets its status
changed and a link. That keeps the history of why things changed.

## In YAAP

- Add one line to the project memory with `update_memory` under *Decisions*, pointing to the ADR, so every later
  conversation sees the decision without reading the folder: "Sessions live in the database (docs/adr/0007)."
- For a decision that needs a design first, use the `brainstorm-design` skill, then record the outcome here.
- When the user wants to edit the draft together, open it in the document panel with `open_document` (in a project
  conversation); elsewhere, show the draft in the reply.

## Template

```markdown
# NNNN. <Decision as a short phrase>

- Status: Proposed | Accepted | Rejected | Deprecated | Superseded by [NNNN](NNNN-title.md)
- Date: YYYY-MM-DD
- Deciders: <names or roles>

## Context

<The problem and the forces at play, without the solution. What happens if nothing is decided.>

## Options

### <Option A>
- Good: <...>
- Bad: <...>
- Cost to reverse: <low / medium / high, and why>

### <Option B>
...

## Decision

<We will ... , because ...>

## Consequences

- Easier: <...>
- Harder: <...>
- To do: <follow-up work, migrations>
- Risks: <what could prove this wrong, and how we would notice>

## Links

- Supersedes / related to: <ADR links>
- <issues, designs, benchmarks>
```

Versions

RepositoryScoreLicence
This page · jelvodev/yaap100MIT
aAAaqwq/AGI-Super-Team100MIT
khuynh22/agent-dev-team100MIT
chatquill/claude-code-websites90MIT

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

  • 90architecture-decision-record
    Document a significant technical decision with its context, alternatives, consequences, and status. Use for: architecture decision record, ADR, technical decision log, technology choice.
  • 100adr-author
    Authors Architecture Decision Records (ADRs) that capture context, considered options with trade-offs, the chosen decision, and its consequences. Use this skill when the user wants to write, draft, document, or revise an architecture decision, an ADR, a design decision record, a…
  • 100architecture-decision-record
    ADR templates in the Nygard format with context, decision, consequences, and alternatives. Use when writing ADRs, recording an architectural decision, or evaluating options.
  • 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…
  • 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.
  • 100decision-record
    Log a significant decision with context, options, choice, and consequences so it is not reopened without reason. Use when choosing an architecture, tool, policy, data format, or project direction.

Feedback and reports

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