Record A Decision

Record a decision — write an ADR under decisions/

The platform /open-knowledge skill still governs every markdown operation here (grounding, linking, the rule that OK's MCP tools own in-scope markdown); this skill layers ADR craft on top.

An Architecture Decision Record is a small, dated, frozen document that captures one decision, the forces that made it necessary, and what the team now has to live with. The value compounds over years: a reader who joins in three years should understand not just what was decided but why it was even a question. ADRs are frozen once accepted — you never rewrite one to change your mind, you supersede it with a new record and leave the old one standing as history. That supersedes chain is what separates an honest decision log from a pile of stale opinions.

Filenames are NNNN-title.md (zero-padded 4-digit sequence + kebab title). Status vocabulary: proposed / accepted / deprecated / superseded. Template id decision, body sections exactly ## Context, ## Decision, ## Consequences in that order.

Step 0 — Confirm a decision was actually MADE (HARD GATE)

An ADR records a decision; it does not make one. Before anything else, establish that a choice has been settled.

• If the user is still weighing options, comparing approaches, or asking "should we do X or Y?" — they do not have a decision yet. Stop and route them to the /frame-a-proposal skill. A proposal is where options get explored and argued; an ADR is where the settled outcome gets recorded. Recording a decision the user has not made produces a fake record that misleads every future reader.
• If the user says "we decided X" but you cannot tell what lost or why, ask one question: "What were the alternatives, and what made you pick this one?" An ADR with no rejected options is a press release, not a record.
• If the thing in question is whether the design itself is sound — not the record of it — hand off to /review-a-design. This skill assumes the decision is sound; it captures it.

Do not proceed past this gate until the user has confirmed a specific decision. State it back to them in one sentence and get a nod.

Step 1 — Scan for prior art (surface supersedes candidates BEFORE writing)

A new ADR that silently contradicts an accepted one is how a decision log rots. Before allocating a number, find what already exists.

1. search({ query: "<subsystem or topic of the decision>" }) — semantic sweep for related decisions, proposals, and specs.
2. exec("ls -A decisions/") — see the existing sequence and titles.
3. exec("grep -rln <subsystem-keyword> decisions/") — find records touching the same subsystem, interface, or constraint.
4. For each promising hit, exec("cat decisions/NNNN-x.md") — read its Decision and Status.

Then classify and surface to the user before writing:

• Contradicts an accepted record → this new decision reverses or replaces it. Flag the path as a supersedes: candidate: "This looks like it supersedes 0007-use-rest-api, which is currently accepted. Confirm and I'll wire the chain in Step 7." Do not silently write a contradicting record.
• Extends without contradicting → note the related record; you'll link it, not supersede it.
• Genuinely new → proceed.

If the decision graduated from an accepted proposal in proposals/, locate that proposal now (exec("grep -rln <topic> proposals/")) — you'll link it as the parent in Step 4.

Step 2 — Allocate the next number and create from the template

Never guess the sequence number. List the folder and take the next integer.

1. exec("ls -A decisions/") — read the highest existing NNNN.
2. Next number = highest + 1, zero-padded to 4 digits. First-ever decision is 0001.
3. Pick a short kebab title naming the decision, not the topic: 0012-adopt-event-sourcing-for-orders, not 0012-orders.
4. Create it from the template:

write({ document: { path: "decisions/0012-adopt-event-sourcing-for-orders.md", template: "decision" } })

The template lays down the frontmatter scaffold and the three H2 sections. Fill the frontmatter now:

type: decision
description: "One line: the decision, active voice."
status: proposed        # proposed until the deciders accept; then accepted
date: YYYY-MM-DD        # today
deciders: [<user>]      # who owns this decision
supersedes: []          # fill in Step 7 if this replaces an earlier record
tags: [decision]

Leave status: proposed while drafting. It becomes accepted only when the deciders sign off (Step 8) — an ADR that ships accepted before anyone agreed is backdating.

Step 3 — Context: the forces at play (invest here)

## Context is the section that ages best. Write it so a reader three years from now understands why this was even a question — no access to the meeting, the thread, or your memory. Cover:

• The state of the system when the decision was forced — what exists, what's under strain.
• What changed to make a choice necessary now rather than never. A new requirement, a scaling limit hit, a deprecated dependency, a deadline.
• The constraints that bounded the options — team size, existing tech, latency budgets, compliance, a hard date.
• The forces in tension — the reason this is a decision and not an obvious call. If there were no competing pressures, there'd be nothing to record.

Write it neutrally and factually. Do not argue for the decision here — that's Step 4's job. Context describes the problem so completely that the Decision reads as one reasonable response to it. If a reader finishes Context and still can't see why a choice was needed, the section has failed; rewrite it.

Ground every factual claim about the system in something checkable — link the proposal, a spec, or a prior decision rather than asserting from memory.

Step 4 — Decision: active voice, one paragraph, unambiguous

## Decision states what will be done, in the active voice, present or future tense: "We will ..." One clear paragraph. A reader must finish it knowing exactly what was chosen with zero ambiguity.

Then, briefly:

• Name the options that were weighed and why the others lost. Two or three sentences per rejected option is enough — "We considered X but it couldn't meet the latency budget; Y was simpler but locked us to a single vendor." This is the heart of the record; a decision with no visible alternatives is unverifiable.
• Link the parent proposal if the decision graduated from one: "This decision accepts 0004-orders-rearchitecture-proposal." Plain markdown relative link, never backticked, never an HTML anchor.

Do not fold implementation detail into the Decision — how it gets built belongs in a spec, not the ADR. The Decision says what and why, not the migration steps.

Step 5 — Consequences: both directions, honestly

## Consequences records what the team now lives with — good AND bad. A Consequences section with only upside is a marketing document, not an ADR. Cover, in whatever grouping fits:

• What gets easier — the wins that motivated the choice.
• What gets harder — the costs, the new complexity, the thing that's now more awkward.
• What new obligation the team carries — ongoing maintenance, a new skill to hire for, a dependency to track, an invariant someone must now uphold.
• What this forecloses — options you can no longer take cheaply, doors this closes.
• Neutral consequences — facts that are neither win nor loss but that a future reader needs.

Force yourself to write at least one genuine negative and one new obligation. If you can't find any, you haven't thought hard enough — every real decision costs something. The negatives are the most valuable part of the record; they're what a future team checks when the decision starts to hurt.