Decision records
The Chronicle is where a project keeps its reasoning: why something is shaped the way it is, what was tried and rejected, and what a decision cost. Tickets record what happened; the Chronicle records why it was right.
It exists because the expensive knowledge in a fleet-built system is not in any diff. A ticket says "switched the carrier to Pub/Sub". The Chronicle says which three alternatives were measured, which one looked obviously correct and was not, and what the failure mode of the winner is.
Writing records — /batondeck:chronicle
In practice you do not write these by hand. You run the sweep and your agent writes them from evidence already on the board:
/batondeck:chronicleIt reads the finished tickets — descriptions, deliverables, the DONE / NEXT / REJECTED / UNCERTAIN checkpoints, PR and branch artifacts — and lays that out as records, citing every paragraph
back to the ticket it came from. It is incremental — a cursor marks what has already been swept.
The sweep is currently limited to the BatonDeck repo: half of it is a pair of deterministic scripts that live there rather than shipping in the plugin. Elsewhere the command stops with a message naming the path it could not find. Writing and reading records is not limited — that is the rest of this page. See Commands for the detail.
To write one directly — a document nobody generated — ask for that instead: "open a Chronicle record for why we chose Pub/Sub over the Firestore tail."
The underlying tools, if you are building against the API
| Tool | |
|---|---|
create_chronicle_page | Start a record by hand — a document nobody generated |
ingest_chronicle_page | Publish a generated record into the hosted surface |
edit_chronicle_page | Commit a new version — every edit is a new version, nothing is overwritten |
delete_chronicle_page | Destroy a record, every version of it, and its stored blocks |
Records are versioned, not mutable. An edit adds a version; the history stays readable. That is deliberate: a decision record that can be quietly rewritten is worth less than no record, because you can no longer tell what was believed at the time.
Structure
A page is a list of typed blocks — prose, tables, diagrams, callouts, evidence folds. Blocks keep their identity across versions, so a diff between two versions is meaningful rather than a wall of changed text.
Records carry a kind (an ADR, a finding, a sweep) and a topic registry, so the set stays navigable as it grows past the point anyone can hold in their head.
Reading it
The web app's Chronicle screen carries search, filtering by kind, and sorting by added or updated. A record links to the tickets it came from, so you can move from "why" to "what happened" in one step.
What belongs in one
Good records share a shape:
- The decision, stated plainly — what was chosen.
- What was rejected, and why — the part that saves the most time later, and the part most often skipped.
- The measurement — numbers, not adjectives. "826s → 293s" beats "much faster".
- What was not verified — the limits of the evidence, so the next reader knows what is still open.
A record without the rejected alternatives tends to get re-litigated within the month, because nothing tells the next person that the obvious idea was already tried.
