Record a decision — write an ADR under decisions/

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.