open-knowledge-pack-software-lifecycle-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.

Step 6 — Soundness self-check (adversarial pass before committing)

Read the draft as a skeptic who disagrees with the decision. Answer each honestly and fix what fails:

• One-way door or reversible? Is the reversibility of this decision stated? A one-way door (hard or expensive to undo) must say so explicitly in Consequences — that's the single most important thing a future reader needs to know before they inherit it.
• Does Context actually motivate the Decision? Or does the Decision arrive from nowhere, with forces in Context that don't point at it? If the two sections don't connect, one of them is wrong.
• Would a reader who disagrees find their objection addressed? The strongest counter-argument should appear somewhere — in a rejected option or a named consequence. If the obvious objection is missing, add it.
• Is any consequence being hidden because it's inconvenient? The cost you'd rather not write down is exactly the one that belongs in the record.

If this pass reveals that the design itself is in question — not the quality of the record but whether the decision is right — stop and hand off to review-a-design. This skill records sound decisions; it is not the place to relitigate one.

Step 7 — Supersedes chain (both directions or it's broken)

If this record replaces an earlier one, the chain must be wired in both directions or the log lies from one side.

1. Forward, on the new record: add the old path to supersedes: frontmatter.

edit({ document: { path: "decisions/0012-adopt-event-sourcing-for-orders.md",
  frontmatter: { supersedes: ["decisions/0007-use-rest-api.md"] } } })

2. Backward, on the old record: flip its status and add a forward link so a reader landing on the old decision is sent to the new one.

edit({ document: { path: "decisions/0007-use-rest-api.md",
  frontmatter: { status: "superseded" } } })

Then add a line near the top of the old record's Context (or a short > Superseded by ... note): Superseded by [0012-adopt-event-sourcing-for-orders](./decisions/0012-adopt-event-sourcing-for-orders.md).

Never edit the old record's Context, Decision, or Consequences prose. ADRs are frozen — the old decision was true when it was made and stays on the record as history. You add the status flip and the forward pointer; you do not rewrite what it said. Both edits land, or the chain is broken in one direction and the log becomes untrustworthy.

Step 8 — Link and validate

• Backlinks in: ensure the parent proposal links forward to this decision, and any spec that implements this decision links back to it. links({ kind: "backlinks", docName: "decisions/0012-adopt-event-sourcing-for-orders" }) to see who points here; add the missing ones so the record is discoverable.
• Dead links out: links({ kind: "dead", sourceDocNames: ["decisions/0012-adopt-event-sourcing-for-orders"] }) returns clean — zero dead links. Fix or remove every one; a broken link to a superseded record defeats the whole chain.
• Frontmatter complete: type, description, status, date, deciders, supersedes, tags all present and correct.
• Status reflects reality: if the deciders have accepted, flip status: proposed → accepted. If they haven't, leave it proposed and tell the user it's awaiting sign-off. Do not mark a decision accepted on the user's behalf.
• Body shape: exactly ## Context, ## Decision, ## Consequences, in order. No extra top-level sections — depth that doesn't fit these three belongs in a linked spec.

Step 9 — Recap to the user

Close in conversation, three things:

1. The decision in one sentence — the "We will ..." line.
2. Its biggest consequence — the one cost or obligation the team most needs to remember, especially if it's a one-way door.
3. Any record it superseded — name the old ADR and confirm the chain is wired both ways.

Then note whether status is accepted (deciders signed off) or proposed (awaiting sign-off), so the user knows what, if anything, is still open.

Non-goals

• Don't decide on the user's behalf. If no decision has been made, route to frame-a-proposal. This skill records; it does not choose.
• Don't rewrite an accepted record. ADRs are frozen. To change a past decision, supersede it (Step 7) and leave the old one standing — never edit its Context/Decision/Consequences prose.
• Don't fold implementation detail into an ADR. The migration plan, the API shape, the rollout steps belong in a spec (write-a-spec). The ADR captures what and why, not how.
• Don't record a decision that has no consequences section. A record with only upside, or with no costs and no new obligations, isn't an ADR — it's marketing. Every real decision costs something; find it and write it down.
• Don't judge the soundness of the design here. If the question is whether the decision is right rather than whether it's well-recorded, that's review-a-design.