nikiforovall/plugins/handbook-reflect/skills/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/ (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)

| Block | Class | When | |---|---|---| | Bullets | <ul class="bullets"> | 4–6 substantial parallel items. Each <li> leads with <b>…</b> — then a sentence. Mono em-dash marker auto-rendered. | | Artifact grid | <div class="artifacts"> w/ .artifact cards | Files created/modified. 2-col grid. Each card: .tag.added/.modified/.removed, .path (mono), .purpose (sans). Banned: bulleted list of file paths. | | Decision rows | <div class="decisions"> w/ .decision rows | Locked-in choices + rejected alternatives. Two columns ("Chose" / "Rejected") with reason underneath. | | Code/output | <pre class="codeblock"> | Real command + output (8–10 lines max). .ln spans for line numbers. | | Pull-quote | <div class="pullquote"> | One italic Newsreader sentence + mono attribution. For Title subtitle or a punchline slide. | | Two-column prose | <div class="cols2"> | Dense paragraphs. Use for Problem when there's a story to tell. |

Slide shell (every body slide)

<section class="slide" id="sN">
  <div class="eyebrow reveal"><span class="num">0N</span> SECTION</div>
  <h2 class="title reveal"><em>Italic part</em> <span class="roman">roman tail.</span></h2>
  <div class="hairline reveal"></div>
  <div class="body">
    <!-- one of the content blocks above -->
  </div>
  <div class="hairline reveal"></div>
  <div class="footer reveal">
    <span>EYEBROW · CONTEXT</span>
    <span class="right">project / status</span>
  </div>
</section>

The eyebrow + numbered title hairline anchors the top, the bottom hairline + footer rail anchors the bottom. Both are mandatory — they prevent the "floating bullets in a void" failure mode.

Title slide

Distinct layout (no eyebrow, no body):

<section class="slide title-slide" id="s0">
  <div class="pitch reveal"><em>Italic pitch</em> <span class="roman">roman tail.</span></div>
  <div class="meta reveal">SOLUTION RECAP <span class="sep">·</span> PROJECT-OR-CONTEXT</div>
</section>

Density (avoid empty slides)

The biggest failure mode is sparse slides — 3 short bullets in the upper third, the rest of the viewport empty. Counter it:

• Use the full viewport. Body content fills the middle 60–70vh between the title hairline and the footer rail. If you have less, switch to a richer content block (artifact grid, decision rows, code block) before adding padding.
• Substantial bullets only. 4–6 bullets, each a full sentence with a bolded lead. If you only have 2 short bullets, merge with adjacent content or switch block types.
• Footer rail is mandatory. Eyebrow + context on the left, project/status in italic on the right.
• Banned: floating bullets in the top third with >40% empty viewport below.

Typography rules

The template hard-codes these — don't override:

• Hero / slide titles → Newsreader italic, weight 500. Mix italic + roman in one title (<em>…</em> <span class="roman">…</span>).
• Body prose & bullets → system sans, clamp(0.95rem, 1.25vw, 1.1rem).
• Eyebrows / footer rail / mono labels → JetBrains Mono uppercase, letter-spacing: 0.14–0.18em.
• Inline code → <code>literal</code> — the template enforces display: inline so it does NOT break across lines. Never wrap a code span in a flex-column container.
• Forbidden fonts: Bodoni Moda, DM Sans, Plus Jakarta Sans, Space Grotesk, Archivo Black, Outfit, Fraunces, Cormorant, Inter, Roboto, Arial.

Animation guidance

See assets/animation-patterns.md for the slim crib sheet (entrance variants, what NOT to do, common breakage). The default .reveal class with stagger is already wired in template.html.

CSS gotcha

Do not negate CSS functions directly. right: -clamp(...) is silently ignored. Use right: calc(-1 * clamp(...)).

---

Files in this skill

• SKILL.md — this file: taxonomy, render workflow.
• assets/template.html — working starter deck. Light by default, dark toggle, all six content blocks pre-styled, keyboard nav + IntersectionObserver wired. Copy-and-fill, don't rebuild.
• assets/viewport-base.css — copied verbatim from frontend-slides. Inline its full contents in the <style> block of the generated deck.
• assets/animation-patterns.md — slim animation reference (variants, don'ts, troubleshooting).
• scripts/analyze_session.py — JSONL compressor (duplicated from the reflect skill, independent). Strips system reminders, preserves real user messages, collapses tool calls/results to one-liners. Output is markdown to stdout. Use only for explicit sessions — never on the current in-context session.
• reference/example-deck.md — fully worked example showing how a real session maps to the seven sections (treat as inspiration for tone and density, not a template).

Workflow

Default (no args) — recap current session:

1. From conversation memory, walk the taxonomy: title, problem, solution, artifacts, decisions, verification, followups. Drop everything that's journey-not-outcome.
2. For each section, pick a content block. If a section has thin content, switch block types or merge.
3. Resolve temp dir, derive slug.
4. Read assets/template.html and assets/viewport-base.css.
5. Copy the template to <temp>/reflect-solution/<slug>.html. Inline viewport-base.css into the <style> block. Replace placeholders. Add/remove body slides. Update nav rail.
6. Open with start "" <path>.

Explicit session — /reflect-solution <id-or-path>:

1. Resolve to a JSONL path (if just an id, look under ~/.claude/projects/<encoded-cwd>/<id>.jsonl).
2. Run scripts/analyze_session.py <path>. Skill is forked, so the compressed transcript is safe in context.
3. Extract the taxonomy from the transcript yourself.
4. Fallback to JSONL when transcript is lossy. Transcript truncates tool args/results and long messages. When detail matters (full file lists, full diff, full user goal statement), Read the JSONL directly with offset/limit scoped to the relevant turn.
5. Steps 2–6 from the default workflow.

Notes

• The deck is the elevator pitch, not the changelog. If you find yourself listing every Edit, you're recapping the journey, not the solution — collapse to artifacts.
• If verification was absent, say so. A missing-evidence slide is more useful than a fabricated one.
• Decisions slide should include what was rejected and why, not just what was chosen.
• The skill is free to evolve its style independently of frontend-slides. Re-copy viewport-base.css if you want to pick up upstream improvements.