Session To Guideline

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).
   • Skills created / Memories saved — these are the reusable assets; explain why.
   • Tool errors / failed commands — these become the Pitfalls section.
   • Artifacts — the files the operator ends up with.

4. Synthesize the guideline following references/guideline-template.md. Fill every section. Rules:

   • Write for a future operator with the same goal — instructive, not a log.
   • Turn each steering turn into a guardrail ("the AI tended to X → state Y up front").
   • For each skill/memory created, state the reusable problem it solves and when to invoke it.
   • Rewrite weak prompts into the stronger version the reader should use.
   • Quote sparingly; summarize tool activity into phases.

5. Write the deliverable into the weekly folder. The bucket is the ISO week bucket line from the facts sheet Metadata (YYYY/Www, ISO-8601 week of the session start). Default location, unless the user says otherwise:

   <cwd>/Prompt stories/<YYYY>/W<WW>/<Topic>.md   # e.g. Prompt stories/2026/W30/Hermes memory pressure.md

   mkdir -p the week folder first. (Do NOT write it inside a skill folder.) Name the file after the session name/topic. Begin the file with the YAML frontmatter block (see references/guideline-template.md), filled from the facts sheet:

   ---
   session: <8-char id>
   week: <YYYY/Www>
   type: <development|planning|research|documentation|other>   # copy "Session type" verbatim
   model: "@fast"           # ALWAYS quote — an @-prefixed role is INVALID YAML unquoted
   premium: <true|false>          # copy the "Premium candidate" flag verbatim
   premium_reason: "<reasons from the flag, or empty>"
   upgrade_status: <pending|done|n/a>
   # --- the next two ONLY when the facts sheet has an "OpenSpec changes" line ---
   openspec_changes: [<change-name>, ...]
   proposal_excerpt: "<the facts sheet 'Proposal excerpt' line, or omit if none>"
   ---

   • model MUST be quoted ("@fast", "@research"): a YAML plain scalar cannot start with @ (reserved indicator) — unquoted model: @fast makes the whole frontmatter invalid. It is the model that generated THIS story. A subagent cannot observe its own runtime model, so when spawning SessionGuideline the parent MUST state it in the prompt (e.g. generated-by: @fast) and the subagent writes that verbatim. Getting this wrong mis-routes the upgrade queue (a budget story stamped @research never gets re-run). Inline (non-subagent) runs: use the model you are actually running as.
   • type is classified deterministically by the extractor (Session type line: code files → development, proposal/design/spec files → planning, research docs / many searches + no code → research, docs → documentation, else other). Copy it; only override if the narrative clearly contradicts the signal.
   • openspec_changes / proposal_excerpt appear only when a proposal is attached to the session (the extractor found openspec/changes/<name>/ in the session's files/commands and prints an OpenSpec changes line). Omit both fields entirely when that line is absent — do not invent a proposal link. When the write-up references images (storyboards, screenshots), link them relative to the story file — from a week folder that is ../../Projektek/<Project>/.../shot_01.png — and verify each resolves. Tell the user the path.

6. Mark premium stories for later Opus upgrade. Premium is decided deterministically by the extractor — the facts sheet's Premium candidate flag is yes when the session created a skill/memory, OR had ≥5 user prompts, OR produced a facts sheet ≥ ~10K tokens. You do NOT judge it; you transcribe it. Set upgrade_status:

   • pending — premium: true AND a budget model wrote this story (@fast/@compact); it is a candidate for an Opus re-run.
   • done — @research/Opus wrote it (already premium quality).
   • n/a — premium: false.

   When upgrade_status: pending, append one row to the queue index <cwd>/Prompt stories/_premium-queue.md (create with the header if missing):

   | week | story | model | reason | status |
   |------|-------|-------|--------|--------|
   | 2026/W30 | 2026/W30/<Topic>.md | @fast | heavy steering (7 prompts) | pending |

   A later upgrade pass re-runs each pending story on @research/Opus, overwrites the file, and flips both its upgrade_status and the queue row to done.