ckb/.agents/skills/ckb-decide/SKILL.md
Michał Kopeć 7863115b74 Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script
- 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>
2026-09-24 20:45:09 +02:00

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:

  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

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.