chemenu/instructions/capture-session.md

---
type: types/instruction.md
name: capture-session
description: How to save a finished Claude Code session as one or more raw/notes/ transcripts and ingest each one, including how to cut a multi-topic session and why the ingests must not run in parallel.
manual: true
---
# Capture a finished session into the wiki

A working session produces knowledge that exists nowhere else: why a design came out the way it
did, what was tried and rejected, what a command actually printed. When the session ends, that
is gone. This procedure turns it into a `raw/` source and then into compiled pages, so a later
session can look it up instead of re-deriving it.

**Run this only when asked, by name.** It is `manual: true` for a reason: capturing every
session would fill `raw/` with material nobody will ever cite, and the judgment of "was this
session worth keeping" is the user's, not the agent's. Nothing links to this file from
`AGENTS.md` or a skill, and nothing should - a link there is exactly how a deliberate procedure
stops being deliberate.

<!-- wikitool:toc -->
## Contents

- [Where a session's output belongs](#where-a-sessions-output-belongs)
- [When to run](#when-to-run)
- [Steps](#steps)
  - [1. Cut the session into topics](#1-cut-the-session-into-topics)
  - [2. Fix the fidelity before writing a word](#2-fix-the-fidelity-before-writing-a-word)
  - [3. Write each transcript](#3-write-each-transcript)
  - [4. File what is still open, before ingesting](#4-file-what-is-still-open-before-ingesting)
  - [5. Ingest, one transcript at a time](#5-ingest-one-transcript-at-a-time)
  - [6. Verify the set, not just the last one](#6-verify-the-set-not-just-the-last-one)
- [Decision points](#decision-points)
<!-- /wikitool:toc -->

## Where a session's output belongs

Three surfaces, three jobs. Collapsing them is the failure this procedure exists to prevent.

| Surface | Holds | Lifetime |
|---------|-------|----------|
| `raw/notes/` | The transcript - **evidence** of what was said and done | Permanent, immutable |
| The issue tracker | What is still open: decisions not made, work not done | Until closed |
| `kb/` | What was learned, compiled into pages that stay true | Permanent, maintained |

A transcript is not a to-do list and not a project status. Live work belongs in issues, where it
has state and closure; a chat trace kept as the record of "what is happening now" forces every
later reader to reconstruct the state from a log. When this procedure finds an open thread in a
session, it files an issue and the transcript merely records that it did.

## When to run

- The user asks to capture, save, or ingest "this session" / "diesen Thread".
- A session ended with decisions or findings that exist only in its own scrollback.

Not for: a routine session that changed nothing worth citing, and never automatically at the end
of a session.

## Steps

### 1. Cut the session into topics

One transcript per topic, one topic per transcript. A session that fixed a bug, reorganised the
issue board, and argued about harness behaviour is three files, not one.

The reason is downstream: one raw file gets one source page, and a source page's `summary:`,
`entities:` and `concepts:` describe *one* thing. A three-topic file produces a source page that
describes none of them well, and every page citing it inherits that vagueness. Cutting late is
expensive - splitting a raw file after ingest means renaming a file every citation points at.

Cut where the *subject* changes, not where the day did. Signals that two stretches are one
topic: they share an artifact (the same module, the same issue), or one is the verification of
the other. Signals that they are two: a different part of the stack, a different audience for
the answer, or one is about the wiki and the other about the harness that operates it.

When a finding spans two topics, put it in **one** transcript in full and let the other
reference it by name. Two half-accounts produce two source pages claiming the same fact, which
`lint` will not catch because both are individually well-formed.

### 2. Fix the fidelity before writing a word

Capture is layered, and **the layer is decided at capture and never rises afterwards.** No
citation syntax and no later review can promote a paraphrase to a quote; only going back to the
original can, and a session's scrollback will not be there to go back to.

So decide, per passage, before writing:

- **Verbatim** - the user's instructions, decisions and objections; real command output; issue
  text quoted from the tracker. Anything a later page might quote or a reader might need to
  check word-for-word.
- **Paraphrase** - the agent's reasoning, the shape of an argument, what was read in what order.
  Condensed on purpose. A page citing this may cite it, but must not quote it.
- **Second-hand** - material that reached the session through an intermediary: a subagent's
  findings, a summary of a document nobody in the session opened. **Name the intermediary in
  the transcript**, because the provenance chain has a party in the middle whose fidelity is an
  assumption.

If a passage is likely to be load-bearing - a number, a path, a version, a command line, a
decision the user made - quote it verbatim now. Promoting it later is not possible.

### 3. Write each transcript

Filename: `raw/notes/Conversation Transcript - <Topic> Session <YYYY-MM-DD>.md`. Match the
existing files; a comma in the topic phrase is fine and correctly quoted on write.

Every transcript opens with a header block declaring what the reader is holding:

```markdown
# Conversation Transcript - <Topic> Session

> Source: Claude Code session (`<model>`), <workspace> workspace
> Collected: <YYYY-MM-DD>
> Participant: <name>
> Fidelity: **faithful summary transcript, not a verbatim log.** <What is quoted verbatim, what
> is condensed, and whether command outputs are real.>
> <Any second-hand material and its intermediary.>
> <Whether credentials appeared.>
> <If the session was cut: one of N transcripts, and what the others cover.>

<Two or three sentences: what this covers, which commits and issues resulted.>
```

Then the body, in turns. Per turn: the user's instruction verbatim as the heading or first line,
what was read or run, what was decided **and what was rejected**, and the evidence. Rejected
alternatives are the highest-value part and the first thing lost - a page can record what the
code does, but only the transcript records what it deliberately does not do.

Close with an outcome table: version, commits, tests, issues touched, CI.

Write the file with `Write`. Never with a shell heredoc: a transcript is long, and a heredoc
gives the user no diff to review.

### 4. File what is still open, before ingesting

Any thread the session left open - a gap in the tooling, an unchecked assumption, a decision
needing the user - becomes an issue now, not a paragraph in the transcript. Then the transcript
records the issue number, and the transcript stays what it is: evidence.

### 5. Ingest, one transcript at a time

Run `wiki-ingest` per transcript. **Sequentially. Never in parallel**, even when delegating to
subagents.

Concurrent ingests of the same corpus collide in three places, and each collision is a silent
lost write rather than an error:

- **Shared entity pages.** Two transcripts from one session almost always touch the same
  entities. Two agents running `touch` or `xref add` against the same file overwrite each other.
- **Generated files.** `kb/index.md`, `kb/log.md` and `kb/provenance.md` are rebuilt wholesale;
  the last writer wins and the others' entries vanish.
- **`publish`.** Two commits racing on one branch, and the Mass-Update Gate's `--confirm` token
  digests a file list that the other run is still changing.

When delegating, give each subagent its own `WIKITOOL_SESSION_ID` so the budget is scoped per
transcript rather than shared - see [session-setup.md](session-setup.md). Several ingests are
several planned units, which is what makes a fresh id legitimate rather than a way around a
refusal ([gates.md](gates.md)).

Start the next one only after the previous has published and its tree is clean.

### 6. Verify the set, not just the last one

After the final ingest:

```bash
tools/wikitool sources coverage
tools/wikitool lint
```

`coverage` must report every new transcript as covered and no raw file claimed by two source
pages - the specific failure a badly cut session produces. `lint` must be clean.

## Decision points

- **One transcript or several?** Several, unless the whole session had one subject. The cost of
  over-cutting is a few extra source pages; the cost of under-cutting is a source page that
  describes nothing precisely, and it is paid by every page that cites it.
- **Is this worth capturing at all?** The test is whether a later session would ask a question
  this transcript answers. "We shipped a release" is in the changelog. "We rejected the obvious
  design and here is why" is not, and that is what earns a transcript.
- **Does the transcript go in before or after the work is published?** After. A transcript
  written before the verification step records intentions, and the point of it is to record
  what actually happened, including the parts that did not work.
- **The session discussed the harness, not the wiki.** Still worth capturing, in its own
  transcript. It ingests into entities about the tooling environment rather than the stack, and
  keeping it separate is what stops those pages from bleeding into the wiki's own concepts.