/session-recap

Session Recap

Reconstruct what happened in a past core session — from a high-level summary down to verbatim owner quotes — by reading the raw session transcripts (complete, crash-proof, unbiased), not the curated relay/handoff notes.

**Usage**: `/session-recap [last | <session-uuid-prefix> | list] [detail hint]`

Why transcripts, not notes (owner design, 2026-07-13)

1. Relay/handoff notes are short and reflect my curation — bias by construction. 2. Notes need a graceful exit; the transcript JSONL is appended by the harness live, so accidental restarts lose nothing. 3. Only the transcript has *verbatim* detail ("what did the owner say exactly").

Notes remain useful as a fast index into a long session — nothing more.

How to run it

1. **Bound the session.** `python3 skills/session-recap/scripts/extract.py list` prints recent sessions (newest first: file uuid, start/end ISO, message counts, first user line). Cross-check with `<workspace>/state/session-starts.log` (one JSONL line per core boot; consecutive entries bound a session). "last" = the second-newest transcript (newest = the running session). 2. **Extract.** `python3 skills/session-recap/scripts/extract.py dump --session last --filter dialog --max-chars 0` → chronological `[ts] USER:/ASSISTANT:` stream. `--filter user` for owner messages only (verbatim-quote lookups: just grep this). `--filter all` adds tool-call names + system lines when the recap needs to cover actions, not just conversation. `--max-chars 0` = no cap. 3. **Summarize with a CHEAP model** (owner requirement — transcripts run to tens of MB; never burn core-model quota on this). Spawn an Agent-tool subagent with `model: haiku`, hand it the dump (or the dump file path if huge — have it Read in slices), and ask for: timeline, tasks processed + outcomes, PRs/commits, decisions, errors + fixes, **artifacts (files/notes/memories written — the dump's `Write(path)`/`Edit(path)` tool lines carry the paths; owner requirement 2026-07-13)**, loose ends. Match the detail level the owner asked for. **Drop routine operational noise** (owner rule 2026-07-13): battery-escalation ladders, idle proactive-loop passes, quota checks, watcher restarts, memory syncs, health-check green runs — none of it belongs in a recap unless it materially changed the session's course (e.g. quota exhaustion forced a pivot, a crash lost work). 4. **Deliver** to the asking channel. For a verbatim-quote request, skip the subagent entirely — grep the `--filter user` dump and quote directly.

Required summary structure (owner requirement 2026-07-13)

Any work-summary the recap produces — boot catchup, human brief, or an on-demand "summarize what I did" — MUST cover these sections (scale depth to the request, but never drop a section that applies):

1. **Executive summary** (lead with it): the **main initiative(s)**, the **high-level goal**, and the **important decisions — especially architecture/design decisions** (the *why*, not just the *what*). One-line status at the end. 2. **Detailed body**: per-item technical detail — PRs with what each did + why + hazards hit, decisions + rationale, errors + their fixes, **artifacts written** (files/notes/memories — from the transcript's `Write`/`Edit` tool lines), loose ends. When the owner asks for "more detail," expand this — specific findings, exact fixes, reproductions, CI/tooling mechanics — not just more headlines. 3. **Roadmap relationship** (when the work maps to `roadmap/ROADMAP.md`): which track/lane it advances and how (e.g. "closes Track-14 gap (a)"), plus a pointer to the relevant plan doc. 4. **Recommended next actions**: prioritized, naming the **owner-gated blockers with exact commands** (what unblocks the biggest thing first), then the follow-on work.

Save durable work-summaries under `<workspace>/notes/work-summaries/YYYY-MM-DD.md` (owner-created folder 2026-07-13), one file per summary, each opening with a `*[workflow, summary] — author | window | requested-by*` line.

Automatic recap on restart (owner directive 2026-07-13)

**Primary consumer: the next session's agent** (owner 2026-07-13). The boot recap is how the fresh core catches up properly — deeper and less biased than relay notes (which are short, curated, and lost on crash-exits). The human-facing room post is the secondary product.

On each core boot, `/schedule-crons`' final step runs this skill twice-in-one: 1. **Agent catchup (the point):** generate a structured recap of the previous session tuned for the agent — open loops, in-flight PRs + their exact states, pending owner asks, decisions + their rationale, artifacts written, errors whose fixes are unverified. Generating it at boot puts it directly in the new session's context; also write it to `<workspace>/state/last-session-recap.md` so anything else can read it. 2. **Human brief:** if `recap_room` is set in `<workspace>/hosts/<hostname>/recap.json` (sibling of crons.json, which stays a bare job list) and a previous session transcript exists, produce a ~10-line recap of the previous session — what shipped, key decisions, owner asks left open, artifacts written; routine ops dropped — and post it to `recap_room` via gateway op:message. **Privacy (owner rule 2026-07-13): `recap_room` MUST be a private, owner-only room** — a recap can contain anything from a session (drafts, credentials context, private conversations). Never point it at a shared/team room; when in doubt, skip the post and leave the recap on disk under `data/session-recaps/`. Idempotence: stamp `<workspace>/state/last-recap-session.txt` with the recapped session uuid; skip if it already names that session (protects mid-session /schedule-crons re-runs from duplicate posts). Deep recaps stay on-demand.

Notes

• Read-only over transcripts; never edit or move them.
• Transcript dir: `<workspace>/.claude-sutando/projects/<repo-slug>/*.jsonl` (the script resolves it).
• A session that spans compaction stays ONE file; a restart starts a new file — so file