/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/ (mkdir -p). Write the deck as <temp>/reflect-solution/<slug>.html.

Slug rules — kebab-case, derived from the solution (not the session id):

• 2–5 words, lowercase, hyphen-separated, ASCII only
• describe what was shipped (e.g. auth-middleware-rewrite, reflect-solution-skill-design)
• if the solution is unclear, fall back to <YYYY-MM-DD>-<topic>

Open with start "" <path> (Git Bash on Windows).

How to render — fill the template, don't rebuild

The starter at assets/template.html is a working deck: light theme by default (with a dark toggle persisted in localStorage), full slide shell, all six content blocks pre-styled, keyboard nav (↑/↓/Space/PageUp/PageDown/Home/End/j/k), touch swipe, IntersectionObserver reveals, nav rail, and prefers-reduced-motion respect.

Workflow

1. Read assets/template.html and assets/viewport-base.css.
2. Copy the template to your temp output path as the deck's starting point.
3. Inline the full contents of assets/viewport-base.css into the <style> block where the abridged base styles live (the comment marks the spot). Don't link to it — the deck must be a single self-contained HTML file.
4. Replace the {{...}} placeholders with extracted content.
5. Duplicate / remove body-slide <section> elements as needed for your taxonomy. Keep one slide per taxonomy section by default; split if a section overflows density limits (see below). Update the nav rail <a> list to match.
6. Pick the right content block per slide (see catalog) — don't default to bullets.
7. Validate density and font/style rules before saving.

Light theme is the default

<html data-theme="light">. Do NOT change this. The dark theme exists as a user-toggleable option (button bottom-right, key persists in localStorage). Both themes are wired; just leave them alone.

Content block catalog (copy from template, fill in)