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](./decisions/0007-use-rest-api.md), 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:

```yaml
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

`##