Overview
A decision journal records what you knew, what you chose, and what you expected, written before the outcome exists. Memory rewrites all three once the result is known, so the journal is the only defense against grading past reasoning with the answer key in hand. The note type and required fields are in vault-frontmatter-schema.
Write the entry before the outcome exists
Write at decision time, not review time. A reconstruction records the story you now tell, which is what 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 entries are reviewed.
Freeze the pre-decision section
Everything written at decision time is frozen: date, chosen option, alternatives, assumptions, expected outcome, confidence, emotional state. Only outcome and lesson are added, and only at the resolution review.
An edit to a frozen field is a hindsight rewrite and a critical audit finding (C005), not a warning. Version control is the enforcement: a diff against a section that should never change is the evidence. That is one reason a decision-carrying vault belongs in Git (team-vaults).
Record alternatives and the atoms that drove the choice
alternatives_considered and key_atoms are the two fields a hurried author drops, and the two that make an entry useful later.
Alternatives make the decision falsifiable; an entry with one option records that something happened, not that a choice was made. Key atoms create a backlink trail, so opening a claim years later shows every decision it informed and exposes an assumption that is load-bearing across six. Those atoms must be sourced (source-verification).
Honor the expected resolution date
expected_resolution_date turns a journal into a feedback loop. Query weekly for decisions past it. An entry open past its date is a warning (C007), not a footnote. At resolution, append what happened, which assumptions held and which broke, a calibration read on confidence_at_decision, and one lesson written as its own atom so future decisions can link it; a lesson buried inside a decision note is invisible to the rest of the vault.
Review by class, not one by one
Group resolved entries by decision_class, stakes, and reversibility and look for patterns.
- 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: do hard-to-reverse decisions get more deliberation than easy ones?
Run this quarterly (vault-maintenance). The framework that governs how a decision is argued (ADR, MECE, IRAC) is chosen in rigor-frameworks.
Run a pre-mortem on high-stakes entries
Assume it is 18 months later and the decision failed, then write the three likeliest causes. Add the checkable ones to key_assumptions and let the resolution review test them. Assumptions that recur across pre-mortems deserve their own atoms (atomic-notes). The agent prompt for this is in vault-orchestration.