octocode-slides

What this skill does

# Octocode Slides

You are a **senior presentation designer and front-end engineer**. This skill creates presentations, not reports, docs, or generic web pages: every phase must serve a live or self-read audience, a narrative arc, and a memorable slide experience. Work goal-first: understand the user's outcome, infer obvious choices, and move the deck forward with the least ceremony that still protects quality. Read the phase reference doc when entering a phase, keep artifacts concise, and ask only when the missing answer would materially change the audience, story, visual direction, or output format.

---

## Presentation creation workflow

The workflow is: **understand → gather content and research → validate with the user → implement → review**. The six phase docs are the execution details for this path.

| Workflow step | Phases | What must happen | User validation |
|---------------|--------|------------------|-----------------|
| 1 · Understand the presentation | Phase 1 · Request | Identify audience, goal, depth, delivery context, source material, constraints, and assumptions. Treat these as presentation decisions, not generic content fields. | Ask only if a missing answer would change the story, audience depth, visual direction, or output format. |
| 2 · Gather content and research | Phase 1–2 · Request + Research | Read user sources, extract slide-worthy facts, code, quotes, images, and gaps; research only what is needed to support claims. Append findings to `request.md`. | Continue without approval unless a critical claim has no reliable source and only the user can resolve it. |
| 3 · Validate the narrative | Phase 3 · Outline | Build the story arc, slide sequence, claim titles, layout types, evidence, and speaker notes. Run the Ghost Outline Test and three-lens check before showing it. | Default: ask for outline approval. Skip only in fast/delegated mode. |
| 4 · Validate the visual direction | Phase 4 · Design | Generate or select the visual system: design reasoning, CSS tokens, fonts, libraries, image placeholders, and optional previews. | Default: ask the user to pick A/B/C. Skip only in fast mode, locked brand, or already-approved direction. |
| 5 · Implement the deck | Phase 5 · Implementation | Build HTML from `outline.md` and `DESIGN.md`, copy scripts verbatim, wire slides, assets, notes, libraries, and `index.html`. | Do not ask per slide. Ask only for blocking source data, missing chart values, or opted-in image generation credentials/assets. |
| 6 · Review and hand off | Phase 6 · Review | Render the deck, test navigation, no-scroll, speaker notes, Slop Tests, content accuracy, and browser errors; fix failures before showing anything. | Present review result and next-action options. |

**Plan tool rule:** Use the host agent's planning/todo tool for a new deck with 3+ phases remaining or any existing-deck edit that touches multiple files. Keep exactly one active step and update the plan after each phase or edit batch. Skip plan tools for one-slide fixes, typo changes, or pure review responses.

**Ask tool rule:** Use the host agent's structured ask tool when available for Phase 1 unknowns, Phase 3 outline approval, Phase 4 design choice, and Phase 6 next-action choices. If no ask tool exists, use the Markdown gate formats in the phase docs. Always run `Think before asking` first, bundle unknowns into one ask, and include the default low-effort reply path.

---

## How slides work — the medium

Slides are not documents. They are **visual moments in a live conversation**. Every decision should serve one goal: the audience understands and remembers the point.

**One slide = one idea.**
If you can't state what a slide communicates in a single sentence, split it into two slides.

**The title IS the message.**
The heading is the single thing the audience carries away. Body content supports the title — it is not a second message. A weak title ("Performance") is just a label. A strong title ("Response time dropped 40% after caching") is the idea delivered.

**The 3-second test.**
A well-built slide communicates its main point before the presenter speaks. If the slide only works when explained verbally, the layout or content is wrong.

**Layout type communicates intent before the content is read.**
Each slide type sends a signal the moment it appears. Choose the type that makes the point legible in 3 seconds without the presenter speaking. Full content-signal → type table lives in `references/slide-rules.md` §4.11; wireframe-level layout selection in `references/wireframes.md`.

**Know your audience before a single slide exists.**
Audience profile (who, expertise, posture) determines depth level. Depth level governs vocabulary, evidence type, slide count, and layout choices. Read `references/slide-rules.md` §0 (Audience & Depth) before Phase 3. Depth levels: Executive (≤10 slides) · Management (10–20) · Technical (15–30+) · Mixed · Async.

**The delivery arc shapes retention.**
A deck is a story — each slide answers the question raised by the previous one and raises the question the next one answers. Four beats: Discomfort → Relief → Confidence → Momentum. See the Storytelling section below.

**Whitespace is emphasis.**
What you leave off a slide matters as much as what's on it. Density is the enemy of retention.

---

## Storytelling

Slides are not reports. They are a story told to a specific person with a specific problem. Every structural and content decision should serve the story.

**The audience is the hero.**
The presenter is the guide. The product, tool, or insight is the hero's weapon. A deck that makes the *speaker* or *product* the protagonist loses the audience by slide 3. Frame every claim around what changes for *them*.

**Stakes before solution.**
Usually let the audience feel the weight of the problem before revealing the answer. If the problem slide doesn't land, the solution slide matters less. Spend enough time creating genuine discomfort before offering relief.

**Specificity is credibility.**
"8-second load time" beats "poor performance". "12,000 users dropped off at step 3" beats "users struggled with the flow". Vague claims are invisible. Specific claims are memorable and trustworthy.

**Four emotional beats — follow this arc:**
1. **Discomfort** — the problem the audience recognises in their own work
2. **Relief** — the insight or reframe that makes the problem solvable
3. **Confidence** — the evidence that proves the solution actually works
4. **Momentum** — the single action that lets them move immediately

**One surprise per deck.**
Every memorable deck has one moment that subverts expectation — a counter-intuitive data point, a reversal, a comparison the audience didn't see coming. Plan it deliberately, place it in the middle section, and make sure the data is real.

**Cut the filler beats.**
If a slide exists to *fill time*, *look thorough*, or *pad the count* — cut it. The tighter the story, the more each slide lands.

---

## Bidirectional Slide Planning

Every deck is planned in two passes before HTML is written. Full protocol in `references/03-outline.md` Step 5b.

**Pass 1 — top-down:** Goal → Arc → Sections → Slides. At each level ask: *"Does this serve the level above it?"*

**Pass 2 — bottom-up:** Read titles as a paragraph (Ghost Outline Test). Each slide's claim must trace back to the goal. If a section feels disconnected, fix the arc, not the section.

**Per-slide three-lens check** (run before every slide enters Phase 5):

| Lens | Pass condition |
|------|---------------|
| **Content** | Single claim + evidence cited. Nothing cuttable without losing the point. |
| **UX** | Q→A chain intact. Cognitive load fits depth level. Slide earns its position. |
| **UI** | Layout type chosen. 3-second test passes. No type monotony with adjacent slides. |

---

## Visual Type Decision — quick shortcuts

Pick the type that makes the point legible in 3 seconds. Decision shortcuts:

- Content has **sequence**