ckb/.agents/skills/ckb-decide/SKILL.md

name

description

ckb-decide

Record a decision into wiki/decisions/ as a numbered decision record — what was decided, by whom, when, why, what it affects, and which earlier decision it supersedes or reverses — and answer questions about decisions already recorded ("what did we decide about X", "show decision 7", "which decisions are still open", "what changed the database choice"). Use when the user says "record a decision", "log a decision", "we decided ...", "ADR", "decision record", or asks what/when/why/by whom something was decided. Distinct from `ckb-ingest` (which turns raw source material into entity pages) and from `ckb-retrieve` (general KB questions — this skill is the decisions-scoped path, and hands off to it for anything wider).

Decision log skill

Purpose

A decision is a different kind of knowledge from an entity page. An entity page describes what something is, and gets rewritten as understanding improves. A decision record describes what was chosen at a point in time, by whom, and why — and is never rewritten to reflect a later change of mind. When the choice changes, a new decision supersedes the old one and both stay on the record. That's the whole point: the value is in being able to ask "why is it like this?" and get the reasoning, the people, and the date, not just the current state.

This skill owns both halves of that:

• Recording — turning "we decided X" into a numbered, linked, logged decision record under wiki/decisions/, with the supersession links wired in both directions.
• Looking up — answering questions about decisions already recorded, scoped to wiki/decisions/ rather than searching the whole wiki.

It writes only inside wiki/ (wiki/decisions/, wiki/decisions/index.md, wiki/decisions/log.md, wiki/graph/edges.json, and a pointer line in wiki/log.md). It never edits an existing decision's substance — see Rule: decisions are append-only, below.

Trigger phrases

Recording:

• "record a decision" / "log a decision" / "add a decision record" / "write an ADR"
• "we decided ..." / "we've agreed to ..." / "the call was ..."
• "we're reversing ..." / "that supersedes decision N"

Looking up:

• "what did we decide about X" / "why do we ... ?" (when the answer is a decision)
• "show decision 7" / "show me D-0007"
• "which decisions are still open" / "what's proposed but not accepted"
• "who decided X" / "when did we decide X"
• "what decisions affect <project/system/person>"
• "what superseded decision N" / "what changed the X decision"

For a question that only touches decisions as part of a wider answer, use ckb-retrieve instead and let it pull decision pages in as one source among many. This skill is for when decisions themselves are the subject.

The decision record format

One page per decision at wiki/decisions/NNNN-short-slug.md, numbered sequentially from 0001. Numbers are never reused and never renumbered — a superseded or reversed decision keeps its number and its page.

---
type: decision
tldr: One sentence stating the decision itself, not the topic.
status: accepted
decided_on: 2026-09-01
decided_by: Alice Smith, Bob Jones
affects: /wiki/entities/billing-service.md, /wiki/projects/index.md
review_on: 2027-03-01
supersedes: /wiki/decisions/0003-use-mysql.md
confidence: 0.9
quality: 0.8
last_updated: 2026-09-01
freshness_window_days: 365
retention: high
---

# D-0007 — Use Postgres for the billing store

**Status:** Accepted · **Decided:** 2026-09-01 · **Deciders:** [[Alice Smith]] / [Alice Smith](/wiki/entities/alice-smith.md), [[Bob Jones]] / [Bob Jones](/wiki/entities/bob-jones.md)

## Context

What forced a choice. The problem, the constraints, what was true at the
time. Written so it still makes sense to someone reading it in two years
with none of the surrounding conversation.

## Decision

What was actually decided, stated plainly and in the active voice.

## Rationale

Why this option won. The reasoning that would have to change for the
decision to be worth revisiting.

## Consequences

What follows — what this commits us to, what it rules out, what work it
creates. Both the good and the costly.

## Alternatives considered

What else was on the table and why each was not chosen. A decision record
without this is much less useful on re-reading: it's the part that stops
the same option being re-proposed every six months.

## Supersession

Supersedes [[D-0003]] / [D-0003](/wiki/decisions/0003-use-mysql.md) — MySQL
was chosen before the reporting requirements landed.

## Sources

- `raw/archive/2026-09-21/arch-review.md` — sha256:3f9a2c1e (checked 2026-09-21)

## Crux

> We're going with Postgres. The reporting requirements need window
> functions and nobody wants to maintain a second analytics store.
— `raw/archive/2026-09-21/arch-review.md`, Ana Reyes

A decision record is the page type where ## Crux earns its place most clearly. Everything above it is this skill's reconstruction of a choice; the Crux is the moment the call was actually made, in the words it was made in. When someone later asks "did we really decide that, or did we just discuss it?", a verbatim quote settles it and a summary doesn't — which is also the distinction between status: accepted and status: proposed that ckb-ingest is warned about.

Quote the decision itself, not the surrounding debate; if the material contains no sentence where anyone actually decides, that is strong evidence the record should be proposed. Fingerprint every cited local file (sha256sum <file> | cut -c1-8) so ckb-lint check 12 can tell you when the source underneath a decision changes.

Decision pages carry no ## Notes section. Nothing regenerates them, so there is nothing to protect against — and an append-only record with a freely-editable annotation block invites exactly the retroactive revision the append-only rule exists to prevent.

Field reference

Field	Required	Notes
type	yes	always decision
tldr	yes	the decision itself in one sentence ("Billing uses Postgres"), not the topic ("database choice") — this is what shows in the index and in search results
status	yes	proposed / accepted / rejected / superseded / reversed — vocabulary defined in wiki/decisions/index.md
decided_on	yes for accepted/rejected/reversed	YYYY-MM-DD, the date the call was made. Distinct from last_updated, which is when the page last changed. A proposed decision may have no decided_on yet.
decided_by	yes when known	comma-separated names, kept flat and plain so tooling can read it. The body's Deciders line carries the dual-links to entity pages. If genuinely unknown, write unknown rather than omitting the field — "we don't know who decided this" is itself worth recording.
affects	no	comma-separated project-root-absolute wiki paths this decision constrains. Cheap way to answer "what decisions touch X" without walking the graph.
review_on	no	YYYY-MM-DD to revisit. ckb-lint reports these once the date passes.
supersedes / superseded_by	when relevant	project-root-absolute path to the other decision. Always set both sides (see below).
confidence, quality, last_updated, freshness_window_days, retention	as usual	standard page schema. Decisions default to freshness_window_days: 365 and retention: high — a decision record doesn't rot the way a status page does, and it should survive a retention sweep.

How to run this skill — recording

Step 1 — Collect the facts, ask only for what's missing

Take everything the user already said at face value; don't re-ask for it. Then check what's missing against this list, in priority order:

1. The decision itself — what was chosen. Without this there's nothing to record.
2. Who decided — names. This is the field users most often leave out and most often want later.
3. When — a date. "Today" is fine; "last Tuesday's architecture review" is fine, resolve it to a date.
4. Why — the rationale, and the alternatives that lost.
5. Whether it changes an existing decision — see Step 2.

Ask for the missing ones in a single AskUserQuestion round rather than an interview — this is a recording task, not a discovery interview. If the user is clearly mid-flow and wants it written down now, record what you have, mark the gaps explicitly in the page body (## Rationale → "Not captured at recording time."), and say which fields you left open so they can fill them in later. A decision recorded with gaps beats a decision not recorded.

Do not invent context, rationale, or consequences. If the user gave you one sentence, the record is one sentence plus the metadata — a fabricated ## Consequences section is worse than an absent one, because a later reader can't tell it wasn't real.

Step 2 — Check whether it supersedes anything

Before writing, read wiki/decisions/index.md and scan for a decision on the same subject. If one exists and is still accepted:

• Confirm with the user that the new decision replaces it (don't assume — two decisions can coexist on the same subject at different scopes).
• If it replaces it outright, set supersedes on the new page and, on the old page, set superseded_by and change its status to superseded.
• If it undoes it and returns to the prior state, use the same two links but set the old page's status to reversed instead.
• Never edit anything else on the old page. Its context, rationale, and consequences stay exactly as they were written — that's the historical record.

Both directions must be set. A one-sided supersession link is a lint finding, and it breaks the "what changed this?" lookup in the other direction.

Step 3 — Allocate the number and write the page

The next number is the highest existing NNNN in wiki/decisions/ plus one, zero-padded to four digits — never reuse a number, even if the highest-numbered decision was rejected or superseded. Slug from the decision itself, not the topic: 0007-use-postgres-for-billing.md, not 0007-database.md.

Write the page using the format above. Link deciders to their entity pages where those pages exist (dual-linked, per Rule C). Where a decider has no entity page, write the name as plain text and mention the gap in your report — creating person pages is ckb-ingest's job, not this skill's.

Step 4 — Wire it into the index and graph

• wiki/decisions/index.md — add a bullet in number order: * **[Accepted]** [D-0007 — Use Postgres for the billing store](0007-use-postgres-for-billing.md) — <tldr> and remove the "no decisions recorded yet" placeholder once there's a first entry. When a decision's status changes (Step 2), update its index line too.
• wiki/graph/edges.json — add the edges this decision creates: decided_by (decision → person page), affects (decision → each page named in affects), and supersedes (new decision → old decision) where applicable. Skip any edge whose target page doesn't exist rather than pointing at a page you'd have to invent.

Step 5 — Log it, then report

Log the change in wiki/decisions/log.md (not wiki/log.md) using Rule B's format, and add a single pointer line to wiki/log.md: - See wiki/decisions/log.md for decision-record changes on this date. Per the Recursive Index & Log Convention, each change gets exactly one home log — don't write the full entry in both.

Then tell the user: the number and title assigned, the fields you filled, any fields left open, what it superseded (and that the old page's status was updated), which deciders had no entity page, and the standard reminder that this is on disk but not committed — "say 'sync changes' when you want it pushed."

How to run this skill — looking up

Step 1 — Start at the decisions index

Read wiki/decisions/index.md first. It carries every decision's number, title, status, and one-line summary — enough to answer "which decisions are open", "what's been decided about X", and "which decision covers Y" without opening a single page.

Step 2 — Open the pages that actually matter, and read them fully

For a specific decision, read the whole page — a decision's tldr states the choice but not the reasoning, and "why" is usually the real question. For a subject-scoped question ("what have we decided about billing?"), open every decision whose affects or body mentions the subject, including superseded ones.

Superseded decisions are part of the answer, not noise. "We use Postgres, and before that MySQL, changed in September because of reporting" is the useful answer; "we use Postgres" is the impoverished one. Follow supersedes/superseded_by chains in both directions and present the history in order.

Step 3 — Verify against the source before answering

Apply ckb-retrieve's standing rule: a decision page's ## Sources section points at where the decision came from. When the answer hinges on detail beyond what the page states — exact wording, a number, who was actually in the room — follow the source rather than paraphrasing the paraphrase.

Where the page has a ## Crux, take ckb-retrieve Step 6's shortcut: check the recorded fingerprint against the cited file, and if it matches, quote the Crux directly. If it doesn't match, the source underneath this decision has been edited since the record was written — say so, answer from the source, and flag it. That is worth stating plainly rather than folding into a caveat: a decision record whose evidence has moved is the one case where "what we decided" and "what the record says we decided" can come apart.

Step 4 — Answer with the metadata attached

A decision answer is incomplete without who and when — lead with the decision, then attribute it. State the status plainly, especially when it isn't accepted: an answer built on a proposed or superseded decision must say so in the same breath, or the reader will act on something that isn't in force.

If nothing is recorded on the subject, say so plainly and offer to record one now — don't reconstruct a decision from surrounding wiki content and present it as if it were on the record. If the question revealed a genuine gap, that's a wiki/query-gaps.md entry (ckb-retrieve owns that file).

Rule: decisions are append-only

The only edits this skill makes to an existing decision page are: status, superseded_by, last_updated, and — when the user is explicitly correcting a recording error rather than changing their mind — the factual metadata fields. Context, Decision, Rationale, Consequences, and Alternatives are never rewritten to match a later view.

When the user says "actually we changed our mind about D-0003", that is a new decision superseding D-0003, not an edit to D-0003. Say so and record it that way. The exception is a genuine transcription error ("I said Alice, it was actually Anna") — fix that in place and note the correction in the log entry.

Edge cases

• No wiki/decisions/ directory yet — create it along with index.md and log.md (using the scaffold this template ships), then record the decision as 0001-….
• The user describes a decision that was already recorded — don't create a duplicate. Point at the existing record and ask whether they want to supersede it, correct it, or leave it.
• A decision with no clear decider ("we just kind of settled on it") — record decided_by: unknown rather than guessing or attributing it to whoever is in the room. Unattributed is a fact; misattributed is a defect.
• A decision that was never actually made ("we should probably...") — record it as status: proposed with no decided_on, or don't record it at all. Ask which; a proposal filed as accepted is the most damaging failure mode this skill has.
• A decision that reverses a reversal — normal chaining. Each link points one step back; the chain is the history.
• Bulk import of historical decisions (a meeting-notes backlog) — that's ckb-ingest's job for the extraction, then this skill's format for the pages. Record them in chronological order so the numbers run in the same order as the decisions.

---

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.