diff --git a/patterns/session-explainer.md b/patterns/session-explainer.md index 21df999..4e3e31a 100644 --- a/patterns/session-explainer.md +++ b/patterns/session-explainer.md @@ -35,13 +35,42 @@ If you cannot fetch the template, build the same structure from the requirements ## Required structure -All five are mandatory. A page missing any of them is not this pattern. +All six are mandatory. A page missing any of them is not this pattern. 1. **A sticky left rail** (`.rail`) holding the session's numbers and context. It stays on screen while the content column scrolls, so the reader keeps the session's identity while reading any one part. -2. **Two tabs** — `Highlights` (`#p1`, default) and `Dead ends` (`#p2`). Driven by `:target` and `:has()`, never JavaScript. +2. **Three tabs** — `Highlights` (`#p1`, default), `Dead ends` (`#p2`), `Trace` (`#p3`). Driven by `:target` and `:has()`, never JavaScript. 3. **A compressed timeline** in Highlights. One line per step. This is the index to the whole session. 4. **One card per dead end** in the second tab, `id="dead-N"`. 5. **Deep links from timeline to cards.** A timeline row that has a card is an `` whose gutter reads `dead-N →`. Clicking it switches tab, scrolls to the card, and rings it. Rows without a card stay a `
` and get a plain gutter label. +6. **A trace panel** in the third tab: every turn of the session in order, both sides. See below. + +## The trace panel + +Highlights is an editorial gloss and the cards are narrative. Neither shows what actually happened in sequence, which is the thing a reader most often wants and the thing hardest to fake. The trace panel is that sequence. + +**Ship the input whole and compress the output.** This is the asymmetry that makes it fit, and it comes out of measurement rather than taste. Count both sides of a real session before deciding what to cut: the human's side is usually a rounding error. In the session that produced this pattern, 38 prompts came to about 1,600 words against a 12.2 MB transcript — roughly 0.08% of the bytes. So every prompt ships complete, and the agent's side is what gets budgeted. + +Per turn, show: + +- **Turn number and timestamp**, with a stable `id="tN"` anchor so a reader can link to one turn +- **The human's prompt**, complete. Collapse it behind a `
` above ~40 words, never truncate it away +- **The agent's reply**, collapsed by default, with its first line as the preview and a word count on the toggle so the reader knows what they are opening +- **What the turn did** — tool names with counts, files written, thinking-block count +- A link to the dead-end card if that turn earned one + +**Tool results do not belong here.** They are the bulk of the megabytes and almost none of the meaning. Naming the tool and the count carries the information; pasting the output carries the weight. + +Mark day boundaries when a session spans more than one, and say plainly when a turn produced no reply. + +## Editing policy + +"Verbatim" is the wrong promise. Prompts carry typos, and sessions occasionally touch things that should not be published. Three different problems, three different answers, and the page has to state which it applied: + +- **Typos and dropped words: fix them silently.** No information lives in a misspelling. +- **Rambling, hedging, and changes of mind: keep them.** That is the thinking trail, and it is exactly what makes a trace worth more than a summary. A prompt that wandered should still read like it wandered. Smoothing it turns the trace back into the Highlights tab. +- **Sensitive or private spans: cut them and mark the cut.** Never silently reword. An unmarked edit makes every other line on the page unverifiable, which costs more credibility than the cut saves. + +Keep the edits auditable rather than ambient: a per-turn marker on the turns you touched, and a one-line statement of the rule at the top of the panel. Do not describe the panel as verbatim if you edited it. ## Numbers must be measured @@ -56,6 +85,8 @@ Required in the context block: `agent`, `model`. Add `window`, `repo`, `outcome` | Insights | 2–4 items, **150 words total** | | Timeline rows | 8–16, one line each | | Dead-end cards | 2–6 | +| Trace turns | every one, no cap | +| Agent reply per turn | collapsed by default | | Lede | 2 sentences | | `