Decision log

decision-log

Keep one append-mostly file — {{decision_log}} — holding the project's numbered decisions with status and rationale. It is the project's authority layer: when code, docs, and notebooks disagree, the decision log arbitrates (see layer-sync). Entries are conclusions, not discussions; superseded entries stay in place with a changed status so the derivation chain of the eventual paper stays traceable.

When to use

• An assumption, default, threshold, data source, or method is chosen — especially anything another layer (spec, code, notebook, paper) will depend on.
• A previously accepted decision is replaced, relaxed, or reversed.
• An alternative was seriously evaluated and rejected — negative decisions are entries too; they stop the team from re-litigating.
• A decision is consciously deferred past the current publication target.

When NOT to use

• Implementation details fully visible in the code and its tests — the diff is the record.
• Transient exploration ("let's see this number") — that is a notebook note (project-layout), promoted to a decision only if it changes a default.
• Run evidence and numbers — those live in the build log and {{evidence_dir}}; the decision entry links to them.
• Rewriting history — never edit an old entry's substance; supersede it.

Entry format

Newest entry at the top, directly under the conventions header. Undated founding conventions live at the bottom.

## D<NN> — <one-line imperative title>

**Status**: accepted | superseded (→ D<MM>) | rejected | deferred
**Date**: YYYY-MM-DD

**Context**: why the question arose — 2–5 sentences, with links to the triggering
artifact (roadmap item, audit finding, notebook, failing gate).

**Decision**: the resolution, as numbered items when it has parts. State values
explicitly ("threshold = 0.85"), name the alternative that lost and in one line why.

**Impact**: which layers must change (spec §, module, notebook, status board), whether any
protected default changed (see canonical-params), and what evidence backs the choice
(link to {{evidence_dir}} run dirs or build-log entries).

Runbook

1. Find the next free number: grep -oE '^## D[0-9]+' {{decision_log}} | sort -V | tail -1 and increment. Never reserve numbers in advance; the number is assigned at write time.
2. Check for a predecessor. If this decision changes an existing one, write the new entry, then edit only the old entry's Status: line to superseded (→ D<new>).
3. Write the entry at the top in the format above. Conclusion language, not deliberation transcripts; link the background instead of pasting it.
4. Propagate or schedule. Either update the dependent layers in the same change, or state in Impact what remains — the next layer-sync audit will hold you to it.

Rules

1. One decision per entry. Two questions resolved together are two entries that cross-reference each other.
2. Statuses are exactly: accepted, superseded, rejected, deferred. A superseded entry keeps its body verbatim; only the status line changes.
3. Every numeric default cites a justification — a measurement, a reference, or an explicit "design operating point, to be calibrated" honesty label. Unjustified constants are how silent errors enter papers.
4. The Impact section is a propagation contract. Layers it names are what layer-sync audits; omitting a layer there does not exempt it, it just makes the drift harder to find.
5. Cite decisions by number everywhere else (docs, notebooks, commit messages) — "per D14" — and gloss the meaning on first use in any document ("the count-matching decision (D14)"), so readers never need a lookup table.
6. Findings can be decisions. A negative or infeasibility result that fixes the project's direction deserves an entry with the evidence linked — do not soften it.

Configuration

• {{decision_log}} — the file (default docs/decisions.md).
• {{evidence_dir}} — where linked run evidence lives.

Provenance & maintenance

Generalized from a 50+-entry ADR-lite chain in a working computational-research repository (newest-on-top ordering, four-status lifecycle, supersede-don't-edit, Impact-as-propagation- contract); see the pack's examples/ directory for the worked exemplar mapping. The format block is the exemplar's structure with domain content removed; the four status values and the next-free-number rule are verified practice.

Re-verify in your project:

• grep -oE '^## D[0-9]+' {{decision_log}} | sort -V | tail -1 — highest number = next − 1; duplicates mean a numbering collision to fix.
• grep -cE '\*\*Status\*\*: (accepted|superseded|rejected|deferred)' {{decision_log}} — should equal the entry count.
• head -20 {{decision_log}} — the newest entry must be at the top.