journal

journal

Purpose

Persistent state tracking and Architecture Decision Records across sessions. Journal manages the state files that allow any workflow to span multiple sessions without losing progress — rescue operations, feature development, deploy decisions, or audit findings. Separate from session-bridge which handles general context injection — journal writes durable, human-readable state that survives compaction.

Triggers

• Called by any skill needing decision persistence or progress tracking
• Auto-trigger: after surgeon completes a module, after deploy, after audit phases

Calls (outbound)

None — pure L3 state management utility.

Called By (inbound)

• surgeon (L2): update progress after each surgery session
• rescue (L1): read state for rescue dashboard
• autopsy (L2): save initial health assessment
• cook (L1): record key architectural decisions made during feature development
• deploy (L2): record deploy decision, rollback plan, and post-deploy status
• audit (L2): save AUDIT-REPORT.md and record health trend entry
• incident (L2): record incident timeline and postmortem
• skill-forge (L2): record skill creation decisions and rationale
• graft (L2): auto-log graft operations — source URL, mode, challenge score, files changed
• retro (L2): record retrospective insights and decisions
• improve-architecture (L2): record an ADR when the user rejects a deepening candidate with a load-bearing reason

Files Managed

.rune/RESCUE-STATE.md      — Human-readable rescue progress (loaded into context)
.rune/module-status.json   — Machine-readable module states
.rune/dependency-graph.mmd — Mermaid diagram, color-coded by health
.rune/adr/                 — Architecture Decision Records (one per decision)
.rune/risks/               — Risk Register entries (one per identified risk)

Execution

Step 1 — Load state

Use Read to load current rescue state:

Read: .rune/RESCUE-STATE.md
Read: .rune/module-status.json

If either file does not exist, initialize it with an empty template:

• RESCUE-STATE.md: create with header # Rescue State\n\n**Started**: [date]\n**Phase**: 1\n
• module-status.json: create with { "modules": [], "lastUpdated": "[iso-date]" }

Parse module-status.json to extract current module states and health scores.

Step 2 — Update progress

For each module that was completed during this session:

1. Locate the module entry in the parsed module-status.json
2. Update its fields:
   • status: set to "complete" (or "in-progress" / "blocked" as appropriate)
   • healthScore: set to the post-surgery score (0-100)
   • completedAt: set to current ISO timestamp
3. Mark the active module pointer in RESCUE-STATE.md — update the **Current Module** line to the next pending module

Use Write to save the updated module-status.json.

Use Edit to update the relevant lines in RESCUE-STATE.md (current phase, current module, counts of completed vs pending).

Step 3 — Record decisions (gated by 3-criteria scoring)

For each architectural decision or trade-off made during this session (applies to any workflow — feature development, deploy, rescue, audit):

Step 3.0 — Score the decision

Compute three numeric scores (1–5 each) before opening any ADR file. See references/adr-criteria.md for full rubric.

Axis	What it measures
reversibility	1 = next-sprint reversible; 5 = practically irreversible
surprisingness	1 = obvious to any reader; 5 = future engineer would "fix" without context
tradeoff_strength	1 = no real alternative; 5 = genuinely difficult choice

score = reversibility + surprisingness + tradeoff_strength    # range 3–15
open_adr = (score >= 11) AND (each axis >= 3)

Step 3.1 — Counter-test (anti-fake)

Before writing the ADR, fill in at least one rejected alternative + why. If no credible alternative was actually considered, the decision wasn't a real tradeoff — re-classify as a convention (record in CLAUDE.md or comment, not in .rune/adr/) and skip ADR creation.

Step 3.2 — Open the ADR (if gate passed)

1. Generate filename including the score: .rune/adr/ADR-[NNN]-[slug]-s[score].md where NNN is sequential and score is the 3–15 sum (e.g., ADR-007-postgres-write-model-s13.md)
2. Use Write to create the ADR file with this format:

# ADR-[NNN]: [Decision Title]

**Date**: [YYYY-MM-DD]
**Status**: Accepted
**Workflow**: [rescue | cook | deploy | audit | other]
**Scope**: [affected module, feature, or system area]
**Score**: reversibility=[1-5] / surprisingness=[1-5] / tradeoff_strength=[1-5] / total=[3-15]

## Context
[Why this decision was needed — what problem or trade-off prompted it]

## Decision
[What was decided — be specific, not "we chose X" but "we chose X over Y"]

## Rationale
[Why this approach over alternatives — cite specific constraints or evidence]

## Consequences
[Impact on files/modules/future work — include rollback path if relevant]

## Rejected Alternatives (counter-test — MUST have at least one)
[List what was considered but NOT chosen, and why. This prevents future sessions from re-visiting dead ends. If you cannot fill in this section, the decision wasn't a real tradeoff — DO NOT open this ADR.]
- **[Alternative A]**: Rejected because [specific reason — constraint, performance, complexity]
- **[Alternative B]**: Rejected because [specific reason]. May reconsider if [condition changes].

Step 3.5 — Record risks

For each risk identified during the session (technical, schedule, dependency, security):

1. Generate a risk filename: .rune/risks/RISK-[NNN]-[slug].md where NNN is next sequential number
2. Use Write to create the risk file:

# RISK-[NNN]: [Risk Title]

**Date Identified**: [YYYY-MM-DD]
**Identified By**: [workflow — cook | plan | deploy | audit | adversary]
**Severity**: Critical | High | Medium | Low
**Likelihood**: High | Medium | Low
**Status**: Open | Mitigated | Accepted | Closed

## Description
[What could go wrong — specific scenario, not vague "things might break"]

## Impact
[What happens if this risk materializes — quantify if possible]

## Mitigation
[Actions to reduce likelihood or impact]
- [ ] [Action 1 — owner, deadline]
- [ ] [Action 2]

## Trigger Conditions
[How to detect this risk is materializing — monitoring, alerts, symptoms]

## Contingency
[What to do if risk materializes despite mitigation — the Plan B]

3. Risk classification matrix:

Likelihood \ Severity	Critical	High	Medium	Low
High	🔴 Immediate action	🔴 This sprint	🟡 This quarter	⚪ Backlog
Medium	🔴 This sprint	🟡 This quarter	⚪ Backlog	⚪ Accept
Low	🟡 This quarter	⚪ Backlog	⚪ Accept	⚪ Accept

4. Risks marked 🔴 MUST have mitigation actions with deadlines. ⚪ Accept = documented acknowledgment, no action required.

Step 4 — Update dependency graph

If any module dependencies changed during this session (new imports, removed dependencies, refactored interfaces):

Use Read on .rune/dependency-graph.mmd to load the current Mermaid diagram.

Use Edit to update the affected node entries:

• Change node color/style to reflect new health status (e.g., style ModuleName fill:#00d084 for healthy, fill:#ff6b6b for broken)
• Add or remove edges as dependencies changed

Use Write to save the updated .rune/dependency-graph.mmd.

Step 5 — Save state

Use Write to finalize any remaining state file changes not already saved in Steps 2-4.

Confirm all four managed files are consistent:

• RESCUE-STATE.md reflects current phase and module
• module-status.json has updated scores and timestamps
• ADR files exist for all decisions made
• dependency-graph.mmd reflects current module relationships

Step 6 — Report

Emit the journal update summary to the calling skill.

Output Format

## Journal Update
- **Phase**: [current rescue phase]
- **Module**: [current module]
- **Health**: [before] → [after]
- **ADRs Written**: [count]
- **Risks Logged**: [count] ([severity breakdown])
- **Files Updated**: [list of .rune/ files modified]
- **Next Module**: [next in queue, or "rescue complete"]

Context Recovery (new session)

1. Read .rune/RESCUE-STATE.md   → full rescue history
2. Read .rune/module-status.json → module states and health scores
3. Read .rune/risks/             → open risks and their status
4. Read git log                  → latest changes since last session
5. Read CLAUDE.md               → project conventions
→ Result: Zero context loss across rescue sessions

Constraints

1. MUST record decisions with rationale — not just "decided to use X"
2. MUST timestamp all entries
3. MUST NOT log sensitive data (secrets, tokens, credentials)
4. MUST work for any workflow — never require rescue-specific fields to be present

Sharp Edges

Known failure modes for this skill. Check these before declaring done.

Failure Mode	Severity	Mitigation
ADR written from memory instead of actual session events	HIGH	Only record decisions that were explicitly made in this session — don't reconstruct
RESCUE-STATE.md initialized without content when called from non-rescue workflows	MEDIUM	If caller is not rescue/surgeon, skip RESCUE-STATE.md initialization — use progress.md instead
Overwriting human-written ADR content on re-run	CRITICAL	MUST check if ADR-[NNN].md exists before writing — never overwrite, increment NNN
Empty ADR Rationale field ("decided to use X")	MEDIUM	Constraint 1 blocks this — re-prompt for rationale before writing
Opening an ADR for a decision that scores below threshold (sum < 11 or any axis < 3)	HIGH	Step 3.0 gate — if score fails, classify as "convention" and record in CLAUDE.md instead
Score inflation to reach threshold	MEDIUM	Step 3.1 counter-test — must name a credible rejected alternative; cannot be faked
ADR for a deferral ("we'll do X later")	MEDIUM	Deferrals are not decisions; route to backlog or .out-of-scope/ (if rejection)

Done When

• All decisions from the session that pass the 3-criteria gate (sum >= 11, each axis >= 3, counter-test filled) recorded as ADR files
• Decisions failing the gate classified as conventions (logged in CLAUDE.md or code comment, NOT in .rune/adr/)
• All identified risks recorded as RISK files with severity, mitigation, and trigger conditions
• Progress state updated (module status, phase, or deploy event as appropriate)
• Dependency graph updated if module relationships changed
• Journal Update summary emitted to calling skill
• No existing ADR files overwritten

Cost Profile

~200-500 tokens input, ~100-300 tokens output. Haiku. Pure file management.