Overview
A decision journal records what you knew, what you chose, and what you expected, written before the outcome exists. Memory rewrites all three the moment the result is known, so the journal is the only defense against grading your own past reasoning with the answer key in hand. The note type and its required fields are defined in vault-frontmatter-schema.
Journal the decision before the outcome exists
Write the entry at decision time, not at review time. A decision reconstructed after the fact records the story you now tell about the choice, which is the thing the journal exists to check.
---
type: decision
decision_date: 2026-08-29 # immutable
decision_class: capital-allocation # capital-allocation | hire | strategic | trade | personal
reversibility: hard # easy | medium | hard
stakes: high # low | medium | high
expected_resolution_date: 2027-08-29
chosen_option: "Acquire the Tampa warehouse at $4.1M"
alternatives_considered: ["Pass", "Counter at $3.7M", "Different asset class"]
key_atoms: ["[[claim-tampa-cap-rates-compressing]]", "[[FW-minto-pyramid]]"]
key_assumptions: ["Industrial demand holds through 2027", "Tenant renews at CPI"]
expected_outcome: "Stabilized at a 7.5% cap within 18 months"
confidence_at_decision: medium
emotional_state: "Calm, mild time pressure from a competing offer"
resolved: false
outcome: null
lesson: null
---Filenames are date-prefixed (DJ-2026-08-29-tampa-warehouse.md) because chronology is how these get reviewed.
Keep the pre-decision section immutable
Everything written at decision time is frozen: the date, the chosen option, the alternatives, the assumptions, the expected outcome, the confidence, and the emotional state. Only outcome and lesson are ever added, and only at the resolution review.
An edit to a frozen field is a hindsight rewrite and should be a critical audit finding, not a warning. Version control is the enforcement mechanism: a diff against a section that should never change is the evidence. That is one reason a decision-carrying vault belongs in Git, as covered in team-vaults.
Record the alternatives and the atoms that drove the choice
alternatives_considered and key_atoms are the two fields a hurried author drops, and they are the two that make the entry worth anything later.
Alternatives make the decision falsifiable. A journal entry with one option is a record that something happened, not that a choice was made. Key atoms create the backlink trail: years later, opening a claim shows every decision it informed, which is how you discover that one shaky assumption is load bearing across six decisions. Those atoms must be sourced, per source-verification, or the trail leads to nothing checkable.
Set an expected resolution date and honor it
expected_resolution_date is what converts a journal into a feedback loop. Without it, entries accumulate and no one ever grades them.
Query for decisions past their date every week. At resolution, append four things: what actually happened, which assumptions held and which broke, the honest calibration read (was confidence_at_decision right?), and one lesson written as its own atom so it can be linked from future decisions. A lesson buried inside a decision note is invisible to everything else in the vault.
An entry that stays open past its resolution date is a warning-level finding, not a footnote. See vault-audit.
Review decisions by class, not one at a time
Single decisions teach almost nothing; classes of decisions teach a lot. Group resolved entries by decision_class, stakes, and reversibility, then look for the pattern.
- Calibration: on high-confidence decisions, how often was the expected outcome right?
- Class skew: which class has the worst record, and does it share an assumption?
- Reversibility discipline: are hard-to-reverse decisions getting more deliberation than easy ones, or the same amount?
Run this quarterly. It is the one review that changes future decisions rather than tidying past notes. The cadence is set in vault-maintenance, and the framework that governs how a decision is argued (ADR, MECE, IRAC) is chosen in rigor-frameworks.
Pre-mortem before high-stakes entries
Before writing a high-stakes decision, run a pre-mortem: assume it is 18 months later and the decision failed, then write the three most likely causes. Add whichever ones are checkable now to key_assumptions, and let the resolution review test them.
This costs ten minutes and converts vague unease into named, falsifiable assumptions that the vault can track. Assumptions that recur across pre-mortems are candidates for their own atoms, per atomic-notes.