Desk Journal

Desk journal

Maintain desks/<desk-name>/journal.md as a concise persistent trail; read the latest entry to resume work or append a new entry that tells the next session what happened, where things stand, and what to do next.

When to invoke

• "Read the desk journal before we continue."
• "Write an end-of-session journal entry."
• "Add a mid-session checkpoint to the journal."
• "Wind down this desk with a final summary."
• "Record what was done, current state, and next step."

Prerequisites and context

• The journal path is desks/<desk-name>/journal.md; infer <desk-name> from the active desk, user request, or repository convention.
• The journal is persistent memory, not a full diary. Keep entries short enough for future sessions to scan.
• If the desk path cannot be inferred, report the missing desk name rather than writing to an arbitrary location.

Journal entry types

Writing rules

• Append to desks/<desk-name>/journal.md; do not rewrite history unless the user explicitly asks to correct an entry.
• Write for someone who knows nothing about the current session.
• Be specific: name repositories, artifacts, commands, decisions, failures, and next files to inspect when useful.
• Include what did not work so the next session does not repeat dead ends.
• Keep normal entries to 3-5 lines; put larger context on the bench as a separate artifact.
• Always include a next step for session entries.

Entry templates

Session or checkpoint entry

## <date> — <short summary>
- **Worked on:** <what was done this session>
- **Current state:** <where things stand right now>
- **Next step:** <what the next session should pick up>

End-of-desk entry

## <date> — Desk closed
- **Summary:** <what this desk accomplished overall>
- **Artifacts:** <what's on the bench from this desk>
- **Handoff:** <anything another desk or the operator needs to know>

Reading rules

Resume discipline

Entries must prevent the next session from having to re-derive the current state. Include enough concrete evidence, artifact names, and blockers to make that possible.

Principles

• The journal is a cairn: every entry is a stone left so the next traveler finds the way.
• Honesty beats completeness; "I got stuck on X and don't know why" is more useful than silence.
• The journal is for the next session, not the current one.
• A vague entry such as "Worked on security scanning" is weak; a useful entry says which repos were scanned, what was found, what was triaged, and what remains.

Output template

## Desk journal result

**Status:** read | appended | blocked
**Journal:** `desks/<desk-name>/journal.md`
**Entry type:** start-of-session | mid-session checkpoint | end-of-session | desk closed

### Entry or latest state
```markdown
## <date> — <short summary or Desk closed>
- **Worked on:** <what was done this session>
- **Current state:** <where things stand right now>
- **Next step:** <what the next session should pick up>

Notes

• <dead end, artifact, handoff, or none>

## Quality gate

- [ ] The journal path is `desks/<desk-name>/journal.md` and the desk name is not guessed when unavailable.
- [ ] Start-of-session work reads the most recent entry before summarizing context.
- [ ] Appended session entries include `Worked on`, `Current state`, and `Next step`.
- [ ] Desk closure entries include `Summary`, `Artifacts`, and `Handoff`.
- [ ] Entries are concise but specific enough for a future session to resume without re-deriving state.
- [ ] Dead ends, blockers, or uncertainty are recorded honestly when relevant.