reflect-tree

# /reflect-tree — session quest-tree

Produce a single-file interactive HTML quest-tree of a Claude Code session. The vertical spine is the linear sequence of turns; back-edges and off-spine nodes encode wrong turns (corrections, retries, reversals, dead-ends, backtracks) so the user can see the whole journey at a glance — including detours and where the agent had to redo work.

This is a **sibling** to `/reflect`. Same input contract, different output: `/reflect` is a two-pane incidents/recommendations dashboard; `/reflect-tree` is a graph.

## When to use

- User invokes `/reflect-tree` (no args) → analyze the **current session** from the in-context conversation. Do **not** re-read the session JSONL — work from the agent's own memory.
- User invokes `/reflect-tree <session-id>` or `/reflect-tree <path-to-jsonl>` → run `scripts/analyze_session.py <path>` directly (this skill runs in a forked context — `context: fork` — so the compressed transcript is safe to ingest). The script outputs a compact markdown transcript: system reminders stripped, tool calls/results collapsed to one-liners, compaction blocks expanded with embedded user quotes. Then **you** classify each turn — the script does NOT classify, it only compresses.

Session JSONLs live under: `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`

## Node classifications

Each turn becomes a node. Pick the strongest applicable label:

- **normal** — routine forward progress (user request or assistant tool call/result with no problem)
- **correction** — user pushed back on an approach (`"no"`, `"don't"`, `"stop"`, `"actually"`)
- **retry** — agent ran the same tool/intent 2+ times with variations before it worked
- **reversal** — agent edited then unwound (Edit → revert, Write → delete)
- **dead-end** — tool failed because of the environment (missing binary, wrong path, OS mismatch)
- **backtrack** — agent abandoned a path and resumed from an earlier state
- **self-correction** — agent caught its own mistake mid-stream

## Edge types

- **flow** (default) — solid thin line between consecutive turns
- **back-edge** — curved dashed line from a retry/reversal/correction node back to the ancestor turn it relates to (color matches the classification)
- **backtrack** — curved solid arrow showing where the agent jumped back to
- **wasted-segment** — thicker grey edge with a `T12–T18 · 7 turns` label when many turns of fruitless searching collapse into one capsule

Each non-normal node carries a `refs` array listing the ancestor turn IDs it relates to.

## Knowledge mining (per-node insight)

Every node must carry an `insight` block — the **single most important, reusable lesson** from that turn, framed so a future agent could drop it into a prompt or rule. This is the value of the tree: each node becomes copyable knowledge.

For each turn, extract:

- **highlight** (1 line, ≤120 chars) — the single most important fact/decision/lesson. The "if you only read one thing from this turn" sentence.
- **insight** (2–5 lines) — the *why* behind the highlight. What the agent learned, what was non-obvious, what a future agent should do differently or keep doing. Phrase it as durable advice, not a play-by-play.
- **prompt_snippet** (copyable text) — a self-contained chunk a user could paste into CLAUDE.md, a memory file, or a future prompt. Must read independently of the tree (no "see T5" references). Format depends on the classification:
  - **correction / dead-end** → a rule: `- Always X, because Y` or a `<rule>` block
  - **retry / waste** → a recipe: the canonical command/path/tool that worked
  - **reversal / backtrack** → a guard: "Don't edit X — edit Y instead" with the reason
  - **self-correction** → a heuristic: "Before doing X, check Y"
  - **normal** (only the load-bearing ones — request, key decision, final answer) → a fact: the goal statement, the chosen approach, the outcome

Skip `prompt_snippet` for filler `normal` turns (routine Reads/Greps with no insight). Better to have 6 strong insights than 50 weak ones.

The HTML drawer renders these per-node with a **Copy insight** button that copies `prompt_snippet` to the clipboard. A header-level **Copy all insights** button assembles every node's `prompt_snippet` into one markdown document grouped by classification.

## Visual language

| Class            | Shape            | Color (CSS token)        | Symbol |
|------------------|------------------|--------------------------|--------|
| normal user      | filled circle    | `--accent`               | —      |
| normal assistant | open circle      | `--fg`                   | —      |
| correction       | diamond          | `--err` border           | `!`    |
| retry            | double ring      | `--warn`                 | `↻`    |
| reversal         | hollow square    | `--warn` dashed          | `⇄`    |
| dead-end         | filled X         | `--err`                  | `✕`    |
| backtrack        | arrow node       | `--muted` dashed         | `↶`    |
| self-correction  | small diamond    | `--ok` border            | `✓!`   |

X-position: normal = center spine; correction/reversal nudged left; retry/dead-end nudged right. This keeps the spine readable while making detours visually distinct.

A legend is rendered inline in the header.

### Collapsed-run capsule

When grouping consecutive `normal` turns into a capsule, render the **entire label inside the rounded rect** — turn-range, count, and topic together. Do not place the turn-range outside the box; it looks broken when the rect background only covers part of the label.

Pattern (SVG):

```html
<g class="capsule" transform="translate(300 380)">
  <rect x="-150" y="-13" width="300" height="26"/>
  <text x="0" y="0">
    <tspan class="turn-range">T120–T139</tspan> · 11 turns · refactor + INFRA_GUIDE.md
  </text>
</g>
```

The rect width must accommodate the full text. Center the `<text>` (anchor middle, dominant-baseline middle) so it sits inside the rect. Use `rx`/`ry` ≥ 8 for the