- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
14 KiB
| name | description |
|---|---|
| ckb-decide | Record a numbered, append-only decision record in wiki/decisions/, or answer questions about decisions already recorded. Use for "record a decision", "we decided ...", "ADR", "decision record", or when asked what/why/who/when something was decided, what superseded it, or which decisions are still open. |
Decision log skill
Purpose
A decision records what was chosen at a point in time, by whom, and why. Unlike an entity page it is never rewritten to reflect a later change of mind — a new decision supersedes the old one and both stay on the record.
This skill owns both recording (turning "we decided X" into a numbered, linked,
logged record under wiki/decisions/, supersession wired in both directions) and
looking up (answering questions about decisions already recorded, scoped to
wiki/decisions/ rather than the whole wiki).
Writes only inside wiki/: wiki/decisions/, its index.md and log.md,
wiki/graph/edges.json, and a pointer line in wiki/log.md. Never edits an existing
decision's substance — see Rule: decisions are append-only, below.
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:
- The decision itself — what was chosen. Without this there's nothing to record.
- Who decided — names. This is the field users most often leave out and most often want later.
- When — a date. "Today" is fine; "last Tuesday's architecture review" is fine, resolve it to a date.
- Why — the rationale, and the alternatives that lost.
- 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
supersedeson the new page and, on the old page, setsuperseded_byand change itsstatustosuperseded. - If it undoes it and returns to the prior state, use the same two links but
set the old page's status to
reversedinstead. - 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 inaffects), andsupersedes(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
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.