268 lines
13 KiB
Markdown
268 lines
13 KiB
Markdown
---
|
|
name: ckb-decide
|
|
description: 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 is never rewritten to reflect a later change of mind: a new one
|
|
supersedes it and both stay on the record. Recording wires supersession in
|
|
both directions; look-up is scoped to `wiki/decisions/`, not the whole wiki.
|
|
Writes only `wiki/decisions/`, its `index.md` and `log.md`,
|
|
`wiki/graph/edges.json`, and a pointer line in `wiki/log.md`.
|
|
|
|
## 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.
|
|
|
|
```markdown
|
|
---
|
|
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`](references/edge-cases.md). Read that file when a
|
|
run hits something the steps above don't cover; don't load it otherwise.
|