diff --git a/patterns/session-explainer.md b/patterns/session-explainer.md new file mode 100644 index 0000000..21df999 --- /dev/null +++ b/patterns/session-explainer.md @@ -0,0 +1,118 @@ +--- +name: session-explainer +description: Explain an agent session — the problem, the approach, the dead ends, and what the thinking actually was. +triggers: + - publish this session + - share this trace + - share my claude code session + - make a page from this transcript + - publish my agent session + - show my thinking on this +brand_sensing: true +brand_scope: colors-only +template: session-explainer.template.html +--- + +# Session explainer + +## When to use + +When the source is an agent session — a transcript of work with a coding agent. The drop's job is to explain **how the author thought about a problem**, not to replay the conversation. The reader wants the reasoning; the transcript is raw material, not the deliverable. + +**When not to use.** If the audience needs unedited proof that the work happened — a grant or accelerator application, an interview artifact, an audit — this pattern is the wrong tool and so is a drop. Those readers want the original file precisely because nobody curated it, and curation is this pattern's whole point. Say so and hand them the raw transcript instead. + +Sessions worth publishing also tend to be the long ones, and a long transcript does not fit in a drop. Distilling isn't a stylistic preference here; it's the only thing that fits. + +## Start from the template, don't invent a layout + +This pattern is **prescriptive**. Unlike the other official patterns it does not offer layout choices, because the structure is what makes these pages comparable to each other. + + curl -s https://htmlbin.dev/.well-known/patterns/session-explainer.template.html + +Fill every `SLOT_*` placeholder and each `` region. The template's CSS is split by a marked line: adapt the **BRAND TOKENS** block, treat everything under **STRUCTURE** as fixed. + +If you cannot fetch the template, build the same structure from the requirements below. Do not substitute a different one. + +## Required structure + +All five 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. +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. + +## Numbers must be measured + +Every value in the rail comes from the transcript. Count it; never estimate, never round for effect. **Omit a tile rather than guess** — a wrong number is worse than a missing one. Mark at most one tile `.hot`, and only when it carries the page's central constraint. + +Required in the context block: `agent`, `model`. Add `window`, `repo`, `outcome` when known. + +## Hard limits + +| Thing | Limit | +|---|---| +| Insights | 2–4 items, **150 words total** | +| Timeline rows | 8–16, one line each | +| Dead-end cards | 2–6 | +| Lede | 2 sentences | +| `