Code Presentation

Generate educational HTML slideshow presentations that explain code changes, new systems, or architectural decisions to a team. The output is a single self-contained HTML file with keyboard/touch navigation, saved to docs/ in the repo.

When to Use

• "Make a presentation about what changed"
• "Create slides explaining this to the team"
• "Generate a deck about this feature/branch"
• "Visual presentation of this work"
• "Explain these changes for the team"

Process

1. Gather Context (Read First, Write Never)

Understand what changed and why before writing a single line of HTML.

Git analysis:

# What commits are we covering?
git log --oneline --reverse <range>
# Detailed commit messages (the "why")
git log --format="%h %s%n%b" <range>
# File-level stats
git diff --stat <range>
# Net change summary
git diff --shortstat <range>

Read key files — prioritize in this order:

1. Documentation created/modified in the change (READMEs, guides, plans, ADRs)
2. Core new files (the main implementation, not every helper)
3. Key modified files (look at the diff to understand what changed, not just the final state)
4. Config/build changes (if architecturally relevant)

Stop reading when you can answer: What was the problem? What was built? Why this approach? What's the impact?

2. Plan the Narrative

Every good technical presentation follows this arc. Not every slide type is needed — pick what fits:

Aim for 8–12 slides. Fewer feels thin, more loses attention.

3. Generate the Presentation

Read the design reference for the full HTML/CSS template with the HSBC-inspired dark theme, slide transitions, navigation, and component library.

Key design principles:

• Self-contained HTML — no external assets except Google Fonts
• Dark theme with brand accent color (adapt to project)
• Groove Jones logo in top-left corner on every slide (base64-embedded SVG, read from assets/gj-logo-white-b64.txt in this skill directory)
• Keyboard navigation (← → Space), touch swipe, clickable progress dots
• Smooth slide transitions (opacity + translateX)
• Fixed bottom navigation bar with progress dots and slide counter
• No frameworks, no build step — opens in any browser

Component library (use these building blocks per slide):

4. Save and Open

Always save presentations — never leave them in /tmp.

Choose the save location based on what the presentation documents:

The principle: co-locate the presentation with the thing it documents. Someone browsing the skill directory or spec directory should find the visual guide right there — not hunt for it in a separate docs/ tree.

# Open in browser after saving
open <path-to-file>.html  # macOS

Tell the user the file path so they can share it.

Quality Checks

Before delivering:

• Narrative arc: Does it flow Problem → Solution → Impact?
• Real content: Are code examples from the actual codebase, not invented?
• Stats are accurate: Line counts, file counts, commit counts match git
• All slides navigable: Arrow keys, dots, buttons all work
• Readable at a glance: Squint test — can you see hierarchy?
• Self-contained: Opens in any browser with no dependencies
• Saved permanently: Co-located with what it documents (skill dir, spec dir, or docs/) — never /tmp

Examples

Trigger: "Make a presentation about the beat engine changes for the team"

Agent workflow:

1. git log --oneline to identify commit range
2. git diff --stat for file change summary
3. Read docs/BEAT_ENGINE_GUIDE.md, BeatEngine.swift, SceneCatalog.swift
4. Plan 12 slides: Title → Problem → Architecture → Data Model → Actions → Audio/Video → Scenes → Controls → DX → Fixes → Roadmap → Summary
5. Generate HTML with syntax-highlighted Swift, architecture diagrams, comparison panels
6. Save to docs/BEAT_ENGINE_PRESENTATION.html
7. Open in browser

Trigger: "Create slides explaining the auth migration"

Agent workflow:

1. git log --oneline main..auth-migration for commit range
2. Read migration plan, key changed files
3. Plan 9 slides: Title → Why Migrate → Old vs New → Migration Steps → Breaking Changes → Rollback Plan → Testing → Timeline → Summary
4. Generate HTML
5. Save to docs/AUTH_MIGRATION_PRESENTATION.html