From 9b6ff5643c58e1833f5227563f6ff61d985e9b5f Mon Sep 17 00:00:00 2001 From: Utkarsh Sengar Date: Sun, 23 Aug 2026 18:27:00 -0700 Subject: [PATCH] patterns: add a trace panel to session-explainer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Highlights is an editorial gloss and the dead-end cards are narrative. Neither shows what happened in sequence, which is what a reader asks for first and the part hardest to fake. A third tab now carries that. The design came out of counting rather than taste. In the session that produced this pattern the human's side is 38 prompts and ~1,600 words, against a 12.2 MB transcript: about 0.08% of the bytes. So the rule is ship the input whole and budget the output. Every prompt appears complete; the agent's reply is collapsed with its first line as the preview and a word count on the toggle; tool results are excluded entirely, because they are nearly all of the weight and almost none of the meaning. "Verbatim" is dropped as the promise, because it can't survive contact with a real session. Three problems, three answers, and the page has to say which it used: typos fixed silently, no information in them rambling, changes of mind kept — that IS the thinking trail sensitive spans cut and MARKED, never silently reworded An unmarked edit makes every other line unverifiable, which costs more than the cut saves. Turns that were touched carry a per-turn marker. The redaction floor now says to scan the agent's replies, not just the prompts. That is the part that gets missed, and building this panel proved it: the first render leaked an employer name, a job title, a customer's real name and an internal URL — every one of them from a reply rather than a prompt, because the agent restated them while being helpful. Third parties and the human's own employer are now cut by default. Template: third tab, the trace styles, and a one-turn skeleton to copy. The default-active tab rule now excludes #p3 explicitly. It has to: `:not(:has(#id))` inherits the id's specificity, so adding a tab without adding it to that chain leaves two tabs highlighted, which is exactly what happened. The e2e asserts the chain rather than the symptom. Verified: tsc clean, 152 e2e checks pass (was 148). Co-Authored-By: Claude Opus 5 (1M context) --- patterns/session-explainer.md | 49 +++++++- patterns/session-explainer.template.html | 97 ++++++++++++++- scripts/agent-e2e.sh | 11 +- src/patterns.ts | 146 +++++++++++++++++++++-- 4 files changed, 288 insertions(+), 15 deletions(-) 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 | | `