decision-journal

Always start by reading:

• decisions.md (root — the centralized journal)

This is the single source of truth for all logged decisions.

2. Route by Subcommand

/decision log — Log a New Decision

Capture a decision from the current conversation. Extract:

1. Decision ID: Next sequential ID using domain prefix (F=Finances, B=Baby, C=Career, H=Home, P=Projects, K=Cooking, HB=Hobbies, I=Interests) + number
2. Title: Short, scannable summary
3. Date: Today's date
4. Domain(s): Which domain(s) this touches
5. Review date: When to revisit (optional — set if the decision depends on changing circumstances)
6. Decision: One-sentence statement of what was decided
7. Rationale: 2-4 sentences explaining why — enough to avoid re-debating later
8. Detail link: If a detailed analysis exists in an archive file, link it

Format (append to the appropriate domain section in decisions.md):

#### {ID}: {Title}
| | |
|--|--|
| **Decided** | {Month Year} |
| **Domain** | {Domain(s)} |
| **Review** | {Review date or trigger, or N/A} |

**Decision**: {One sentence}

**Rationale**: {2-4 sentences}

**Detail**: `{path/to/analysis.md}` *(only if exists)*

---

After logging:

• Confirm what was logged: "Logged as {ID}: {title}. Review set for {date/trigger}."
• If the decision was also captured in a domain context.md, add a cross-reference: "Full rationale: see decisions.md ({ID})"

/decision list — List Active Decisions

Read decisions.md and output a summary table:

# Active Decisions

| ID | Decision | Domain | Decided | Review |
|----|----------|--------|---------|--------|
| F1 | Private school — not pursuing | Finances, Baby | Feb 2026 | ~2030 |
| F2 | Overpay Mortgage 2 only | Finances | Jan 2026 | Sep 2027 |
| ... | ... | ... | ... | ... |

Filters (optional):

• /decision list --domain=finances — Filter to one domain
• /decision list --review — Only show decisions with review dates

/decision review — Surface Decisions Due for Review

Read decisions.md and find decisions where:

1. Review date has passed — The stated review date/trigger is in the past
2. Review date is within 30 days — Coming up soon
3. Key assumption may have changed — Cross-reference with domain context files to detect changed circumstances

Output format:

# Decisions Due for Review

## Overdue
- **{ID}: {Title}** — Review was {date/trigger}. {Why it's relevant now}

## Coming Up (next 30 days)
- **{ID}: {Title}** — Review: {date/trigger}. {Context}

## Assumptions May Have Changed
- **{ID}: {Title}** — {What changed and why it matters}

If nothing is due:

"All decisions are current. Next review: {ID} — {title} ({review date})."

/decision find <topic> — Look Up Past Decisions

Search decisions.md for decisions matching the topic. Match against:

• Decision titles
• Domain names
• Rationale text
• Keywords in the decision statement

Output: Show the full decision entry (ID, decision, rationale, review date).

If no match found: Say so, and offer to check domain context files for related information.

If topic matches a superseded decision: Show both the superseded one and its replacement, with context on why it changed.

3. Passive Capture (During Normal Conversation)

The decision journal isn't only used via the /decision command. During any conversation where a decision is made:

1. Recognize the decision moment — When the user says "let's go with...", "I've decided...", "the plan is...", or a clear choice is made after analysis
2. Offer to log it — "Want me to log this in the decision journal?" (brief, not pushy)
3. If yes, log it — Follow the /decision log format
4. If no, move on — Respect the user's preference; not every decision needs logging

Which decisions to offer logging for:

• Significant choices with clear alternatives considered
• Decisions likely to come up again ("should we..." recurring topics)
• Choices that depend on assumptions that may change (worth a review date)

Which decisions NOT to offer logging for:

• Trivial choices (what to have for dinner)
• One-time actions (buy this specific item)
• Already logged decisions being reconfirmed

4. Cross-Reference with Domain Context

When logging a decision, also update the relevant domain context file:

• If the decision is already mentioned in {domain}/context.md, add a cross-reference: "Full rationale: see decisions.md ({ID})"
• If the decision replaces information in context.md, update context.md to reference the journal rather than duplicating rationale

Don't duplicate — The journal is the single source of truth for rationale. Domain context files should reference it, not repeat it.

5. Superseding & Archiving Decisions

The active journal (decisions.md) is working memory — keep it lean so "check decisions first" stays fast. Retired decisions move to the archive tier (archive/decisions/{year}.md), keyed by the year they were retired. See archive/decisions/README.md.

When a decision is superseded (replaced by a newer one):

1. Move the old decision's full block out of "Active Decisions" into archive/decisions/{year}.md, where {year} is the year the decision is being retired (today's year), NOT the year it was originally decided (create the file with a # Decision Archive — {year} header if it doesn't exist)
2. On the archived block, add: **Retired**: {date} — superseded by {new ID}. {reason for change}
3. In decisions.md under "Superseded / Archived Decisions", leave a one-line pointer: - **{old ID}: {Title}** — superseded by {new ID} ({date}). See \archive/decisions/{year}.md`.` (same retirement year as step 1)
4. Log the new decision as active, with a note: **Replaces**: {old ID}

If the replacement reuses the old ID (a decision revised in place rather than given a new ID — e.g. B3 revised Feb→Mar 2026), disambiguate in the pointer and archived block: refer to the retired one as {ID} (original) and the active one as {ID}. The archived block keeps its original Supersedes/revision history.

When a decision is archived (no longer relevant — the circumstance it governed has passed), do the same but mark **Retired**: {date} — archived ({reason}) with no replacement.

Leave in place: one-time decisions still in force (birth plan, door swing, etc.) stay in the active journal — they're settled, not retired. Only move decisions that are genuinely superseded or no longer relevant.

This creates a clear audit trail — you can always trace why a decision changed, without bloating the working journal.