writing-adrs

name	writing-adrs
description	Guides writing concise, effective Architecture Decision Records. Use when creating ADRs, extracting decisions from specs, or reviewing ADR quality.

Writing Architecture Decision Records

Overview

Architecture Decision Records (ADRs) capture significant technical decisions in a concise, standardized format. They answer "why did we do this?" for future developers and AI agents. DorkOS ADRs live in decisions/ with a manifest.json index.

When to Write an ADR

Write an ADR when a decision:

• Chooses between alternatives — "We picked X over Y because..."
• Adopts a pattern or technology — New library, architecture pattern, data model
• Has lasting consequences — Affects how future features are built
• Would surprise a new team member — Non-obvious choices that need explanation

When NOT to Write an ADR

Skip ADRs for:

• Trivial implementation details — Variable naming, file placement within an established structure
• Obvious choices — Using TypeScript in a TypeScript project
• Temporary decisions — Workarounds that will be replaced soon
• Single-feature scope — Decisions that only affect one spec with no project-wide impact

Writing Guidelines

Context (2-5 sentences)

Focus on the problem, not the solution. What situation existed? What forces were at play?

• Good: "DorkOS runs as both a standalone web app and an Obsidian plugin. The Obsidian plugin cannot make HTTP requests to localhost, so the client needs a way to communicate with the server that works in both environments."
• Bad: "We needed an architecture." (Too vague)
• Bad: A full page of background. (Too long — that belongs in the spec)

Decision (2-5 sentences)

State what was decided in active voice. Start with "We will..."

• Good: "We will use a Transport interface that abstracts the communication layer. HttpTransport handles standalone mode via REST/SSE. DirectTransport handles Obsidian mode via in-process function calls."
• Bad: "The transport pattern was implemented." (Passive, vague)

Consequences

List concrete positives and negatives. Every decision has trade-offs — if you can't list a negative, think harder.

• Positive: Real benefits the project gains
• Negative: Real costs, complexity, or limitations introduced

Decision Signals in Specs

When scanning specs for ADR candidates, look for:

Signal	Example
"We chose X over Y"	Technology or library selection
"The recommended approach"	Pattern adoption after comparing options
"Trade-offs" section	Explicit trade-off analysis
"Architecture" or "Design"	Structural decisions
"We will not" / "Out of scope"	Deliberate exclusions with rationale

ADR Lifecycle

Status	Meaning
proposed	Significant decision recorded, not yet committed
accepted	Active decision guiding implementation
deprecated	No longer relevant (project evolved past it)
superseded	Replaced by a newer ADR (link via superseded-by)
archived	Determined trivial or historical; moved to decisions/archive/

There is no draft status: significance is judged at extraction time. /adr:from-spec applies the significance rubric when extracting — decisions meeting 2+ "When to Write" criteria are written as proposed (or accepted if the spec already shipped); the rest are never written as files.

Partial supersession

When a new ADR reverses part of an older one, the older ADR stays accepted. There is no superseded-in-part status, and inventing one is not the answer: a status is an instruction about whether to rely on the document, and marking a mostly-live ADR terminal tells every future reader to stop reading something they still need.

So:

1. Parent keeps status: accepted and superseded-by: null, in the file and in decisions/manifest.json.
2. Parent's Status section names exactly what is retired: quote the clause, list any Consequences bullets that fall with it, then state what still governs. Follow the shape 260726-170125 uses.
3. Child links back with supersedes: <parent-id> in its manifest entry, and says in its own Status section which clause it replaces. That field is the only machine-readable link, so it is not optional.

Reserve status: superseded for a whole ADR being replaced (0224 → 260726-193526, 0070 → 260726-171347).

One older ADR diverges from this rule: 260713-143958 is a partial supersession that set status: superseded anyway. It predates this rule and is deliberately left alone. Do not copy it, and do not "fix" it either.

Review Gate

/adr:review (triggered when a spec is implemented or the proposed backlog grows)

Moves proposed ADRs to their terminal state:

• Accept (proposed → accepted): Linked spec is implemented and decision is reflected in code
• Deprecate (proposed → deprecated): Codebase diverged from this decision, or context changed
• Supersede (proposed → superseded): A newer ADR replaced this one
• Archive (proposed → archived): Decision is now obvious from reading the code

Acceptance criteria: A proposed ADR is ready for acceptance when:

1. The linked spec has been implemented (status implemented in spec manifest)
2. The pattern/technology/convention described in the ADR is present in the codebase
3. The decision is still actively guiding development (not just historical)

Extraction

ADRs are seeded by the /flow:specify stage (when the flow plugin is loaded) or by /adr:from-spec when a spec is validated. Extraction applies the significance rubric immediately — only decisions that clear it become ADR files.

Common Pitfalls

• Too long — ADRs are not specs. Keep each section to 2-5 sentences.
• Missing negative consequences — Every decision has costs. Be honest.
• Vague context — "We needed a better solution" tells nothing. What was broken?
• Solution in context — Context describes the problem, not the answer.
• No spec link — If a spec drove this decision, always link it.

File Conventions

• Location: decisions/<id>-kebab-case-title.md
• IDs: a coordination-free timestamp YYMMDD-HHMMSS for new ADRs (allocate via .claude/scripts/id.ts); the ~260 legacy ADRs keep their frozen 4-digit numbers, which sort before timestamp ids (spec #271)
• Manifest: decisions/manifest.json tracks all ADRs (no nextNumber counter)
• Template: decisions/TEMPLATE.md for the standard format