| name | journal |
| description | Use at session start, after context compaction, and before session end. Owns session journals in `.sandbox/journals/`: when to create one, what prior context to read, what to log, and how to leave a resumable handoff |
Journal is session memory. It is not a runbook and not generalized reusable learning.
Default posture
Keep journaling useful, not ceremonial.
- For trivial, isolated Q&A, do the minimum
- For file changes, investigations, multi-step work, or anything likely to survive compaction or handoff, keep a real journal
- If a session starts small and becomes complex, open the journal then and add one catch-up entry
Session start
- Ensure
.sandbox/journals/ exists
- Read the newest journal first
- If the newest journal looks related, read only the extra journal(s) needed to orient
- Use a light heuristic: same files, same repo area, same problem, or explicit continuation
- Decide whether this session needs its own journal file. Create one when any of these are true:
- work will touch files or state
- the task is multi-step or investigative
- prior context matters
- Default file name:
.sandbox/journals/YYYY-MM-DD-<kebab-description>.md
- Keep the slug short and task-specific
- If that exact name already exists for a different session, append
-2, -3, and so on
- If a higher-priority instruction defines a different naming scheme, use that scheme and keep the same journal policy
- If the session is complex or resumed, start with a tiny working summary:
- current goal
- most important prior fact or decision
- immediate next action
During work
Append an entry only when it would help a future agent or your post-compaction self.
Good reasons to write:
- a decision changed the plan, with why
- evidence confirmed or killed a hypothesis
- you edited non-trivial files, and why
- you hit a dead end worth not repeating
- you uncovered an open question, blocker, risk, or exact next step
Do not write:
- routine browsing or obvious commands
- long transcripts
- generic principles that belong in the prompt or
napkin
- speculation without an outcome
Entry shape
Use the smallest format that preserves the signal.
## YYYY-MM-DD HH:MM — short summary
- Evidence: `command` -> decisive excerpt
- Decision: what changed, and why
- Files: `path` — why it matters
- Dead end: what failed, and what not to retry
- Next: exact next step
Include only the fields that matter. Combine related micro-steps into one entry.
Reversals and supersession
When you reverse an earlier decision, mark both sides
In the new entry:
> ⚠️ Supersedes: `YYYY-MM-DD HH:MM — prior summary` (reason)
In the old entry:
> ⚠️ Superseded by: `YYYY-MM-DD HH:MM — new summary`
If updating the old entry is impractical, at least mark the new one clearly.
Before session end
Before ending a non-trivial session, append a short handoff entry that says:
- where the work stands
- what is verified
- what remains risky or unresolved
- the exact next action
A good handoff should let the next agent continue without re-reading the whole conversation.
