/reflect-solution

name: reflect-solution
description: Summarize WHAT WAS SHIPPED in a Claude Code session as a self-contained HTML slide deck — the elevator pitch (problem, solution, decisions, artifacts, verification, gaps), not a play-by-play of tool calls or debugging detours. Defaults to the current in-context session; optionally accepts a session ID or JSONL path. Renders directly in the reflect aesthetic — no delegation. Use when the user invokes /reflect-solution or asks for a recap deck of what changed.
context: fork
argument-hint: `<current_session> or <session-id-or-path>`

/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 r