Pages

The Skill

Seven steps from intent to deck. Ten phases of compilation.

transition: slide-left

Seven-Step Workflow

graph LR
  A["Mode"] --> B["Sources"]
  B --> C["Intake"]
  C --> D["Direction"]
  D --> E["Spec"]
  E --> F["Compile"]
  F --> G["Validate"]
  style A fill:#dde3ec,stroke:#3b5f87,color:#2e3440
  style B fill:#dde3ec,stroke:#3b5f87,color:#2e3440
  style C fill:#3b5f87,stroke:#3b5f87,color:#eceff4
  style D fill:#3b5f87,stroke:#3b5f87,color:#eceff4
  style E fill:#dde3ec,stroke:#3b5f87,color:#2e3440
  style F fill:#dde3ec,stroke:#3b5f87,color:#2e3440
  style G fill:#dde3ec,stroke:#3b5f87,color:#2e3440
  linkStyle default stroke:#3b5f87,stroke-width:2px

• Mode — new deck or update to existing
• Sources — gather README, ARCHITECTURE, CHANGELOG, LESSONS_LEARNED
• Intake — normalize title, goal, audience, tone, target length
• Direction — offer 2-3 visual directions in words only
• Spec — write deck.spec.md before any slides
• Compile — generate slides, styles, layouts, components
• Validate — spec matches slides, density controlled, abstractions justified

layout: SplitInsight transition: wipe-right

Source-of-Truth Model

::left::

Planning Layer

• deck.spec.md is the blueprint
• Structure, tokens, boundaries
• Structural changes start here
• Must stay in sync with slides

::right::

Presentation Layer

• slides.md is the compiled output
• Native Slidev Markdown
• styles/, layouts/, components/
• Implementation serves the spec

transition: slide-up

Ten Compilation Phases

1. Gather sources — read project docs, extract facts and stories
2. Normalize spec — resolve meta, tokens, slide and layout inventory
3. Decide level — escalation ladder per slide: Markdown first
4. Write headmatter — theme, fonts, colorSchema, transition
5. Write slides — clean Markdown, one idea per slide, v-clicks on lists
6. Write tokens — --deck-bg, --deck-fg, --deck-accent, --deck-muted
7. Write theme — typography, color application, v-click animations

8-10: Custom layouts, custom components, prune dead code — only when justified.

transition: fade

The Skill Rejects These Patterns

Every item here has appeared in a generated deck at least once.

• No generic stock phrases ("Let's dive in", "In conclusion")
• No ad-hoc transitions — each type has a fixed semantic meaning
• No same layout for every content slide — vary the rhythm
• No hardcoded hex in <style scoped> — use var(--deck-*) only
• No "install command" closings — resolve the opening instead
• No blanket .slidev-layout { background } overrides on themed decks

layout: section transition: iris

Narrative Architecture

Slide kinds, through-lines, and story structure.

transition: slide-left

14 Canonical Slide Kinds

• cover / end — opening and closing frames
• section — chapter breaks that create visual rhythm
• default-content — the workhorse explanatory slide
• center-statement / fact / quote-pull — single-idea emphasis
• split-insight / comparison — side-by-side reasoning
• metrics-grid — comparable metrics in a grid
• image-caption / visual-evidence — image with context

Plus timeline, through-line-echo (resurfaces the deck's thread mid-deck, max 2-3).

layout: TufteSlide transition: slide-up

Through-Line Types

The through-line is the conceptual thread that holds the deck together. It must come from the source material, not be imposed on it.

Five types, each a different rhetorical shape:

• Question — posed early, answered repeatedly
• Metaphor — concrete image mapping to abstract concept
• Concept — technical idea connecting all sections
• Provocation — bold claim the deck proves
• Design-rule — constraint that shaped every decision

::sidenote::

The through-line appears in 5-6 slides, gaining new meaning each time. Cover introduces it. Sections refract it. End resolves it.

Bookend syndrome: the through-line appears only on cover and closing. The middle forgets it exists. This is the most common failure.

transition: morph-fade

Narrative Arc and Structural Rhythm

Every deck follows a four-part story structure:

• Tension — open with a problem, contradiction, or surprising fact
• Exploration — walk through the journey, showing real decisions
• Insight — present a counterintuitive finding or unexpected result
• Resolution — close with a memorable takeaway

Slides alternate in a rhythm: section divider, 2-3 content slides, then a pause (quote, diagram, or fact). Repeat. This prevents visual monotony.

transition: slide-left

War Stories and Source Citations

Every deck of 10+ slides needs at least one war story — a specific moment where something broke or a false trail was followed.

• War stories are concrete, not abstract: "The cache was 2.3 GB" beats "We encountered challenges"
• Every war story cites specific evidence: file path, commit, screenshot
• Every content slide with facts needs a Sources: block in presenter notes

<!-- Presenter notes here...

Sources:
- https://github.com/user/project/blob/main/README.md — overview
- file:LESSONS_LEARNED.md — the production incident
-->

layout: section transition: iris

Quality Gates

Density guardrails, the acceptance checklist, and the priority stack.

transition: slide-left

Hard Limits Prevent Overflow

• 7 bullets maximum per slide — split if exceeded
• 8 code lines maximum per code block — truncate or split
• 60 characters maximum per bullet — rewrite if exceeded
• One idea per slide — if you need to scroll, split it
• 3-5 bullets is normal — one strong stat beats six weak ones

If the slide needs tiny text, the slide needs redesigning.

transition: fade

A Deck Passes When All of These Hold

The acceptance checklist:

• No generic stock phrases, no ad-hoc transitions
• At least 3 different layout types used
• Bullet lists use <v-clicks> for progressive reveal
• At least 1 v-motion element, 1 hover-interactive element
• Mermaid nodes: light fills get dark text, dark fills get light text
• No slide overflows (7 bullets, 8 code lines, 60 char bullets)
• Closing echoes or resolves the opening