reflect-solution

# /reflect-solution — solution recap deck

Produce a single-file HTML slide deck summarizing the **outcome** of a Claude Code session: what shipped, why, and how it was verified. Audience: someone who wants the elevator pitch, not the journey.

Sibling to `/reflect`. Where `/reflect` looks at *wrong turns*, this skill looks at *what was delivered*. Tool-call churn, retries, dead-ends, and reversals are excluded unless they shaped a final decision.

**Self-contained.** This skill ships its own working starter (`assets/template.html`) — fonts, CSS tokens, all six content blocks, IntersectionObserver, keyboard nav, theme toggle. The agent's job is to *fill the template with extracted content*, not to rebuild the scaffolding from scratch.

## When to use

- User invokes `/reflect-solution` (no args) → recap the **current session** from the in-context conversation. Do **not** re-read the session JSONL — work from the agent's own memory of what was built.
- User invokes `/reflect-solution <session-id>` or `/reflect-solution <path-to-jsonl>` → recap a different session. Run `scripts/analyze_session.py <path>` directly (this skill runs forked — `context: fork` — so the compressed transcript can enter your context safely). The script outputs a compact markdown transcript; **you** then extract the solution.

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

## What to extract (menu, not template)

Outcome-focused. Drop the journey. An item belongs in the deck only if it would matter in a PR description.

**The deck structure should fit the session — not the other way around.** Pick from the menu below; skip what's irrelevant; add what isn't listed if the session calls for it. A 3-slide deck is fine. So is 8. Don't pad to hit a count, don't force a section just because it's in the list.

Common sections (use what fits):

- **Title** — one-line elevator pitch of the shipped solution. Always include.
- **Problem / Goal** — what the user brought. Skip if obvious from title.
- **Solution shipped** — components, modules, behaviors. The *what*, not the steps.
- **Artifacts** — concrete files created/modified. Skip if there's only one file or the file list is trivial.
- **Key decisions & tradeoffs** — locked-in choices + rejected alternatives. Skip if the session was straightforward (no real branch points).
- **Verification / evidence** — tests, builds, manual checks. If absent, say so — never invent.
- **Followups / known gaps** — TODOs, deferred work. Skip if there are none.

Other sections that may earn a slide if the session reveals them: stakeholders, deadlines, related tickets/PRs, performance numbers, before/after diff, architecture sketch, a punchline pull-quote.

**Always omit**: session metadata footer (id, date, turn count). The deck is about the solution, not the session.

## Voice and language

The audience is technical (engineers, reviewers). Write like a commit message or a postmortem, not a launch announcement.

- **Direct and factual.** State what is, what changed, what was decided. No hedging, no hype.
- **No marketing language.** Banned: "elegant", "powerful", "seamless", "robust", "leverages", "unlocks", "delivers", "best-in-class", "modern", "clean", "beautiful", "stunning", "delightful". Also banned: rhetorical hooks ("Imagine if…", "What if…"), exclamation points, emoji.
- **No slogans or punchlines.** Every line carries information. Skip the pull-quote slide unless the quote is a real artifact (a user message, a commit subject, a doc heading) — not something invented for flair.
- **No empty connectives.** Drop "In order to", "It is important to note that", "We are excited to". Get to the noun.
- **Concrete over abstract.** "Replaced regex parser with PEG grammar in `parser/expr.ts` — handles nested parens" beats "Improved parsing capabilities".
- **Numbers when you have them.** "12 tests, 94% coverage", "reduced p99 from 240ms to 90ms", "3 files modified, 1 added". Don't invent numbers.
- **Code identifiers in mono.** Function names, file paths, flags, env vars → `<code>`. Prose stays prose.

## Problem statement

This is the most important slide. A reader who only sees this slide should understand what was wrong before the session started. Treat it like the "Background" section of a bug ticket.

- **One paragraph, 2–4 sentences.** Or 3–5 short bullets. Not both.
- **Factual.** State the prior state of the system, the observed defect or gap, and the constraint that forced the work. No motivation language ("we wanted to…"), no story arc.
- **Concrete.** Name the file, the function, the error message, the failing case. If there was a ticket or incident, reference it.
- **No solution preview.** The problem slide describes the problem only. What was done belongs on the next slide.
- **Easy to digest.** Short sentences. One idea per sentence. If you need a comma-spliced run-on to fit, split it.

Good: *The deck template hard-coded a 7-section taxonomy. Sessions with no decisions or no followups produced empty slides. Agents had no guidance on when to drop a section.*

Bad: *We wanted to make the deck more flexible and adaptable so that it could elegantly handle a wider variety of sessions and deliver a more polished experience.*

## Honesty rules

- Be specific. "Added auth handling" is useless; "Added `validateBearerToken()` in `src/auth/middleware.ts`, called from `app.use()`" is a recap.
- Don't invent verification. If no tests were run, the Verification slide says "No automated verification this session — manual smoke check only" or similar.
- Don't pad. A 4-slide deck is fine if the session was small.
- Don't editorialize. Skip adjectives that don't carry information ("nicely", "cleanly", "properly"). If the change was correct, the diff shows it.

## Output

Resolve a temp dir from the environment, in this preference order:

1. `$TMPDIR` (Unix/macOS)
2. `$TMP` or `$TEMP` (Windows / Git Bash)
3. `/tmp` as fallback

Create `<temp>/reflect-solution/` (