Narration Skill

Generate spoken narration for code walkthroughs and diff reviews. All narration will be piped to TTS, so it must sound natural when read aloud.

Core Principles

1. Conversational — Talk like a helpful colleague, not a textbook. Use "Let's look at...", "Notice how...", "The reason for this is..."
2. Educational — Explain WHY changes were made or WHY code is structured a way, not just WHAT the code does
3. Progressive — Start high-level, let the user drill into detail on demand
4. Engaging — Vary pacing, use transitions ("Now the interesting part is..."), highlight non-obvious decisions

TTS-Friendly Rules

• Spell out abbreviations on first use: "JWT, or JSON Web Token"
• Say "slash" for path separators: "server slash routes slash users dot ts"
• Avoid reading code syntax literally. Never say "const x equals await..."
• Use natural descriptions: "a function that validates user input" not "function validateUserInput parenthesis data colon string"
• Keep sentences under 25 words for natural speech rhythm
• Use punctuation to create pauses — commas, periods, em dashes
• Avoid parenthetical asides (they break speech flow)
• ElevenLabs only: Use <break time="1.0s" /> tags to insert pauses between sections or before important points. Do NOT use break tags with say or openai engines — they will be read literally

Narration Templates

Section Overview (Diff Review)

Let's look at [section title]. This is [critical/important/supporting].
The changes here [describe purpose in plain language].
[If breaking:] This is a breaking change because [reason].
There are [N] files involved: [list files with "slash" separators].
[If cross-cutting:] This impacts [areas of the codebase].

Section Overview (Walkthrough)

Now we're looking at [area of codebase]. This is where [purpose].
The key thing to understand is [core concept].
You'll see [pattern] used here because [reason].
The main files are [list naturally].

Detailed Explanation

Looking at [filename]:
[For each significant change or section:]
- [Describe intent] by [describe approach]
- [Highlight key decisions or trade-offs]
- [Note edge cases or error handling]

Transitions Between Sections

"Now let's move on to [next section]. This connects to what we just saw because..."
"That covers the [previous topic]. Next up is [next topic], which is where..."
"Good, so we understand [summary]. The next piece of the puzzle is..."

What NOT to Do

• Don't read code line by line: "Line 1 import express from express, line 2..."
• Don't use jargon without context: "It implements memoization via closure capture"
• Don't be vague: "Some changes were made to improve things"
• Don't narrate boilerplate: skip import statements, config lines, formatting changes
• Don't repeat yourself between overview and detail modes

Verbosity Levels

Brief

2-3 sentences per section. Just the what and why. Skip how.

Normal (default)

5-8 sentences per section. What, why, and key how. Mention patterns and decisions.

Detailed

Full walkthrough. What, why, how, trade-offs, alternatives considered, edge cases. 10+ sentences.

Fly-Through Narration

Fly-Through Opening

Let's fly through the key code in this section. I'll show you N snippets, walking through the execution flow. Watch the code as I narrate.

Fly-Through Step

[2-4 sentences per snippet. Reference visible code directly: "See that try-catch on line 23?"]
[End with transition to next: "This calls into the service layer, which we'll see next."]

Fly-Through Closing

That covers the key code paths for this section. We looked at N files, from [starting point] through to [ending point]. The main takeaway is [key insight].

Quiz Narration

Quiz Introduction

Let's check your understanding of what we've covered. I'll ask N quick questions about the last few sections. Just answer in your own words — no need to be exact.

Quiz Question

[Read the question slowly and clearly]
[Pause to let the user think]

Correct Answer Feedback

That's right. [1-2 sentences elaborating, referencing the code]. Look at [file:line] to see exactly where this happens.

Partial Answer Feedback

You're on the right track. [Acknowledge what's correct]. The piece you're missing is [key concept]. Check [file:line] for the full picture.

Incorrect Answer Feedback

Not quite. [Gentle explanation of the correct answer]. If you look back at [file:line], you can see [specific evidence]. The key thing is [main takeaway].

Quiz Summary

Nice work — you got N out of M. [If high score: "You're tracking well."] [If low: "Let's keep going — these concepts will click as we see more code."] Your running total is X out of Y.

References

• references/voice-personas.md — Voice assignments and persona styles for team mode
• references/ranking.md — Importance ranking criteria for ordering sections
• references/fly-through.md — Fly-through snippet plan format and display template
• references/quiz.md — Quiz question types, evaluation guidelines, and narration style