Narration

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