chemenu/instructions/capture-session.md

type, name, description, manual

type	name	description	manual
types/instruction.md	capture-session	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.	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.

Contents

• Where a session's output belongs
• When to run
• Steps
  • 1. Cut the session into topics
  • 2. Fix the fidelity before writing a word
  • 3. Write each transcript
  • 4. File what is still open, before ingesting
  • 5. Ingest, one transcript at a time
  • 6. Verify the set, not just the last one
• Decision points

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, no later review, no confidence bump 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:

# 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. Several ingests are several planned units, which is what makes a fresh id legitimate rather than a way around a refusal (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:

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.