session-to-guideline

name	session-to-guideline
description	Turn a pi session into a Markdown "how-we-did-it" collaboration guideline: reads the session's JSONL transcript and synthesizes a reusable playbook of which prompts worked, what had to be steered, and how to reproduce the result faster. Use when: "document this session", "write up how we did X with the AI", "make a guideline from this session", "turn this session into a playbook/tutorial".

Session → Collaboration Guideline

Produces a Markdown document that reads like a playbook for collaborating with the AI on a task — not a raw transcript. It separates the goal from the steering, surfaces the skills/memories created and why they work, and ends with a reproduce-it checklist.

Two layers:

1. Deterministic extract (scripts/extract_session.ts) — parses the session JSONL on the active branch and emits a structured facts sheet (prompts in order, tool usage, files written/edited, searches, skills/memories created, failed commands, cost). This is raw material, not the deliverable. TypeScript, run with npx tsx (repo convention).
2. Synthesis — read the facts sheet and write the guideline using references/guideline-template.md. The why it's effective and what to steer parts require judgment. Run it inline for a single session, or delegate to the SessionGuideline subagent for batch / past-session application (see below) — the synthesis is self-contained (facts sheet in, one guideline out), so it isolates cleanly.

Where sessions live

~/.pi/agent/sessions/--<cwd-with-slashes-as-dashes>--/<timestamp>_<uuid>.jsonl (JSONL tree; see the pi session-format docs). The scripts locate files for you.

Worktrees are included by default. A project's OpenSpec work runs in .worktrees/<name> sub-checkouts, which get their own encoded session dir (--<project>-.worktrees-<name>--). Both scripts resolve a --cwd to the project root + every .worktrees/* worktree, so project-scoped listing/latest covers worktree sessions too (rows tagged [wt:<name>]). Pass --no-worktrees for the old root-only behavior. Running from inside a worktree still lists the whole project (the root is recovered by stripping /.worktrees/<name>).

Procedure

1. Pick the session. If the user didn't name one, list candidates:

   npx tsx scripts/list_sessions.ts --cwd "$(pwd)" --limit 20      # this project + its worktrees
   npx tsx scripts/list_sessions.ts --cwd "$(pwd)" --no-worktrees  # project root only
   npx tsx scripts/list_sessions.ts --all --limit 30               # every project
   

   Worktree rows are tagged [wt:<name>] so you can tell root work from worktree work. (tsx runs the .ts directly, no build step.) Show the table and confirm which one (by 8-char id or # index). The current live session is usually #0/latest; documenting a finished prior session gives a complete picture (the live one won't include the not-yet-written tail).

2. Extract the facts sheet (cheap, deterministic). Use a UNIQUE output path per run — the fixed /tmp/session_facts.md is NOT parallel-safe: concurrent runs (e.g. a batch of SessionGuideline spawns) clobber the same file and every reader gets the last writer's sheet. Always mktemp:

   FACTS=$(mktemp /tmp/session_facts.XXXXXX.md)
   npx tsx scripts/extract_session.ts <selector> --cwd "$(pwd)" --out-md "$FACTS"
   

   • <selector> may be an 8-char id, a full path, or latest (use --index N for the Nth most recent). In BATCH runs prefer the explicit JSONL path — the extract's parent-chain walk can drift to a parent file on forked sessions.
   • Use --max-text / --max-cmd to widen truncation if you need more prompt/command text.

3. Read the facts sheet ($FACTS). Pay attention to:

   • Prompt 1 = the goal; prompts 2..N = steering (corrections, scope additions, quality bars, yes/all-three style unlocks).

Batch / past-session application (via the SessionGuideline subagent)

The synthesis is self-contained — facts sheet in, one guideline out, no coherence with any ongoing work — so it is a clean subagent job. For a SINGLE interactive session, running it inline (above) is fine. For applying to MANY past sessions, delegate each to the SessionGuideline subagent so the facts sheet and the reasoning stay out of the main context and sessions don't accumulate there:

1. List the target sessions once:

   npx tsx scripts/list_sessions.ts --cwd "$(pwd)" --limit 50    # or --all
   

2. For each session, spawn SessionGuideline (explicit Agent call), passing the explicit JSONL path (not a partial id — the extract's parent-chain walk can drift to a parent file on forked sessions) + an explicit output path. Each spawn runs BOTH layers in isolation (extract → synthesise) and returns only the written path + a short abstract:

   Agent(subagent_type="SessionGuideline", model="@fast",
         prompt="session JSONL <abs-path>; cwd <dir>; generated-by: @fast; write to the weekly
                 folder Prompt stories/<YYYY>/W<WW>/<Topic>.md (bucket from the facts sheet's
                 ISO week line); add frontmatter; if premium+budget-model, queue it")
   

   Pass the model twice: the Agent(model=…) param sets the runtime model, and generated-by: <same model> in the prompt tells the subagent what to write into model: (it cannot introspect its own model). Keep them identical.
   For bulk backfill on @fast, each spawn writes into its week folder and self-marks premium candidates (upgrade_status: pending) into _premium-queue.md — a later Opus pass drains that queue. See steps 5–6.
3. Collect the returned paths. Parallel batches are safe ONLY because step 2 uses a mktemp facts sheet per run — the old fixed /tmp/session_facts.md raced (concurrent spawns overwrote it, so every playbook got the same sheet). Verify no two outputs share an H1 title before trusting a batch.

Model role. The synthesis is judgment-heavy WRITING on a SMALL, pre-condensed input (the extract script shrinks the JSONL first — it is NOT a long-context job). Quality lives in the insight sections (goal-vs-steering, steering→guardrails, why-skills-effective), where a weak model produces generic slop. Use @research (the subagent's default) for quality. For bulk backfill where cost dominates, @compact is the budget fallback (mechanical sections stay fine; insight degrades) — pass model on the Agent call to override per run.

Selector cheatsheet

Goal	Command
Latest session in this project (+ worktrees)	npx tsx scripts/extract_session.ts latest --cwd "$(pwd)"
Latest, project root only (no worktrees)	npx tsx scripts/extract_session.ts latest --cwd "$(pwd)" --no-worktrees
2nd-most-recent	npx tsx scripts/extract_session.ts latest --cwd "$(pwd)" --index 1
A specific session by id	npx tsx scripts/extract_session.ts 019ea8a9
A session in another project	npx tsx scripts/extract_session.ts latest --cwd /path/to/other
An explicit file	npx tsx scripts/extract_session.ts /abs/path/to/session.jsonl

Notes & pitfalls

• The extractor walks the active branch only (leaf → root via parentId), so abandoned /tree branches are excluded — you document what actually happened.
• Tool names are normalized (mcp__pi__web_search → web_search); skill and memory calls are captured with their action/scope/target so "skills created & why effective" is easy to write.
• The Tokens total includes cache reads, so it can dwarf the in/out numbers — report cost, not raw total, if it looks confusing.
• No third-party deps; TypeScript on Node built-ins (fs/path/os). Run with npx tsx — no compile/build step. Scripts never write to the session store.
• If a session is huge, raise --max-cmds only when you actually need more commands; the default keeps the facts sheet token-cheap.