This skill should be used when the user asks to "create a Debrief trace", "generate a code walkthrough", "make a narrated code explanation", "create a replay trace", "write trace narration", or mentions Debrief traces, JSONL trace files, or code walkthrough generation. Provides comprehensive guidance for writing natural, engaging narration that sounds like a senior engineer explaining code.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
O comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Exibindo SKILL.md
SKILL.md
Instruções da origem · Visualização somente leitura
name
debrief
description
This skill should be used when the user asks to "create a Debrief trace", "generate a code walkthrough", "make a narrated code explanation", "create a replay trace", "write trace narration", or mentions Debrief traces, JSONL trace files, or code walkthrough generation. Provides comprehensive guidance for writing natural, engaging narration that sounds like a senior engineer explaining code.
version
2.4.0
argument-hint
["what to debrief - optional"]
Debrief Trace Authoring
What to Debrief
Topic/scope: $ARGUMENTS
CRITICAL: Do NOT ask the user what they want to debrief or say "the skill is loaded." Act immediately:
If a topic/scope is provided above: Create a trace for that specific topic. Read the relevant files, understand the code, and generate the trace JSONL file immediately.
If no topic/scope is provided (empty or blank above): Debrief everything you have done in this conversation so far. Look at all files you created, modified, or discussed. Walk through each change, explaining what was done and why. Generate the trace JSONL file immediately.
In both cases, start working right away. Read the code, plan the walkthrough structure, and write the trace file. Never ask "what would you like me to debrief?" — the answer is either the argument above or the full conversation history.
Trace file location: Each trace goes in its own subfolder under . The folder and file share the same name:
.debrief/replay/
.debrief/replay/<trace-name>/<trace-name>.jsonl
For example: .debrief/replay/auth-refactor/auth-refactor.jsonl
Choose a short, descriptive kebab-case name for the trace (e.g., auth-refactor, add-caching, fix-race-condition).
This skill teaches how to create Debrief replay traces with natural, engaging narration. The goal is to sound like a senior engineer explaining code to a colleague, not like documentation or a robot.
Highlight Stability
The extension automatically snapshots referenced files when a trace is loaded, so highlights stay accurate even if the code changes later. No special action is needed from the agent — just create the trace normally.
Key Principles
Atomic steps: One highlight per step, one focused thought per narration
Grouped by topic: Related steps are wrapped in sectionStart/sectionEnd for smooth playback
Natural narration: Sound like a senior engineer, not a robot
Trace Format
Debrief traces are JSONL files (one JSON object per line). Each line is a trace event:
{"id":"e1","type":"sectionStart","title":"Authentication","narration":""}
{"id":"e2","type":"highlightRange","filePath":"src/auth.ts","range":{"startLine":10,"startCol":0,"endLine":15,"endCol":0},"title":"Token extraction","narration":"Let's start with how we grab the token from the request."}
{"id":"e3","type":"highlightRange","filePath":"src/auth.ts","range":{"startLine":18,"startCol":0,"endLine":22,"endCol":0},"title":"Token verification","narration":"Once we have it, we verify it against our secret here."}
{"id":"e4","type":"sectionEnd","title":"","narration":""}
Event Types
Type
Purpose
When to Use
highlightRange
Navigate to file + highlight lines
Primary event - use for most explanations
say
Narration only, no navigation
Transitions, summaries, context without code
sectionStart
Begin a group of related steps
Group 2-5 steps that flow together
sectionEnd
End a section
Pair with sectionStart
openFile
Open file without highlighting
Rarely needed - prefer highlightRange
showDiff
Show before/after diff
Code changes, refactoring explanations
Fine-Grained Steps: Break It Down
The #1 mistake is highlighting too much code at once. Large chunks overwhelm users. Instead, break code into small, digestible pieces that are easy to follow.
The Golden Rule
Highlight 2-6 lines per step. If you're highlighting more than 8 lines, you're probably trying to explain too much at once.
How to Break Down a Function
When explaining a function, DON'T highlight the whole thing. Instead:
Step 1: Highlight just the function signature (1-2 lines)
Step 2: Highlight the first logical chunk (2-4 lines)
Step 3: Highlight the next chunk (2-4 lines)
Continue: One concept per step until the function is covered
Example: Breaking Down a Function
Given this function:
asyncfunctionfetchUserData(userId: string): Promise<User> {
const cached = await cache.get(userId);
if (cached) {
return cached;
}
const user = await db.users.findById(userId);
if (!user) {
thrownewNotFoundError(`User ${userId} not found`);
}
await cache.set(userId, user, { ttl: 300 });
return user;
}
BAD: One giant step (13 lines)
{"range":{"startLine":1,"endLine":13},"narration":"This function fetches user data, first checking the cache, then the database, and caches the result."}
GOOD: Fine-grained steps
{"id":"e1","range":{"startLine":1,"endLine":1},"title":"Function signature","narration":"This async function takes a user ID and returns their data."}
{"id":"e2","range":{"startLine":2,"endLine":4},"title":"Cache check","narration":"First, we check if the user is already in cache. If so, we return early."}
{"id":"e3","range":{"startLine":6,"endLine":9},"title":"Database lookup","narration":"If not cached, we fetch from the database and throw if not found."}
{"id":"e4","range":{"startLine":11,"endLine":12},"title":"Cache and return","narration":"Finally, we cache the result for 5 minutes before returning."}
Step Size Guidelines
Lines
Verdict
When to Use
1-2
Perfect
Function signatures, single statements, key lines
3-6
Ideal
Most steps - one logical chunk
7-10
Caution
Only if lines are tightly coupled
11+
Too much
Split into multiple steps
Signs You Need to Split
Your narration contains "and then" or "also"
You're explaining multiple concepts
The highlighted code has blank lines separating logic
You're scrolling to see the whole highlight
More Examples of Fine-Grained Splitting
Explaining a class:
{"id":"e1","range":{"startLine":1,"endLine":3},"title":"Class declaration","narration":"This service class handles all authentication logic."}
{"id":"e2","range":{"startLine":4,"endLine":6},"title":"Dependencies","narration":"We inject the user repository and token service."}
{"id":"e3","range":{"startLine":8,"endLine":8},"title":"Login method","narration":"The main login method takes credentials."}
{"id":"e4","range":{"startLine":9,"endLine":11},"title":"Find user","narration":"First, we look up the user by email."}
{"id":"e5","range":{"startLine":12,"endLine":14},"title":"Verify password","narration":"Then we verify the password hash matches."}
Explaining a config object:
{"id":"e1","range":{"startLine":1,"endLine":2},"title":"Config setup","narration":"Here's our database configuration."}
{"id":"e2","range":{"startLine":3,"endLine":4},"title":"Connection settings","narration":"Host and port come from environment variables."}
{"id":"e3","range":{"startLine":5,"endLine":6},"title":"Pool settings","narration":"We use a connection pool with min 2, max 10 connections."}
{"id":"e4","range":{"startLine":7,"endLine":8},"title":"Timeout settings","narration":"Queries timeout after 30 seconds to prevent hanging."}
One Concept Per Step
One highlight per step
One idea per narration
1-2 sentences max per step
If you say "and then", split into two steps
Steps within a section play with ~100ms pause (feels like continuous speech)
Section Structure
Sections group related steps. Use them sparingly and semantically.
Section Rules
Max 2-3 levels deep - Never nest sections more than 3 levels
Semantic nesting only - Only nest when there's a clear parent-child relationship:
{"type": "sectionStart", "title": "API Layer"}
{"type": "sectionStart", "title": "Database Layer"} // Wrong! Should close API first
{"type": "sectionStart", "title": "Service Layer"} // Wrong! Even deeper nesting
Example: Grouped Steps
{"id":"s1","type":"sectionStart","title":"Request Validation","narration":""}
{"id":"e1","type":"highlightRange","filePath":"src/api/validate.ts","range":{"startLine":10,"startCol":0,"endLine":18,"endCol":0},"title":"Schema check","narration":"First, we validate the request body against our schema."}
{"id":"e2","type":"highlightRange","filePath":"src/api/validate.ts","range":{"startLine":20,"startCol":0,"endLine":28,"endCol":0},"title":"Auth check","narration":"If that passes, we verify the user has permission."}
{"id":"e3","type":"highlightRange","filePath":"src/api/validate.ts","range":{"startLine":30,"startCol":0,"endLine":38,"endCol":0},"title":"Rate limiting","narration":"Finally, we check they haven't exceeded their rate limit."}
{"id":"s1-end","type":"sectionEnd","title":"","narration":""}
{"id":"e4","type":"say","title":"Transition","narration":"With validation done, let's see what happens next."}
Writing Natural Narration
DO: Sound Like a Senior Engineer
Write as if you're sitting next to a colleague, pointing at their screen:
{"narration":"This is where we grab the token from the Authorization header."}{"narration":"If verification fails, we bail out early with a 401."}{"narration":"The clever bit here is how we handle the retry logic."}
DON'T: Sound Like Documentation
Avoid robotic, structured language:
// BAD - sounds like a robot{"narration":"This section contains the authentication middleware implementation."}{"narration":"Line 12 extracts the token. Line 15 performs verification."}
Narration Guidelines
Use conversational phrases: "Let's look at...", "Notice how...", "The key insight here is...", "What's happening is...", "The clever bit is..."
Explain WHY, not just WHAT: Don't just describe code - explain the reasoning, trade-offs, or gotchas.
Connect ideas: Use transitions like "Now that we have X, we can...", "This feeds into...", "Building on that..."
Keep it brief: Each step should be 1-2 sentences. Long explanations should be split into multiple steps.
Avoid announcements: Don't say "Now entering the Authentication section" - just explain the code.
Event Schema
highlightRange (most common)
{"id":"e1","type":"highlightRange","filePath":"src/api/auth.ts","range":{"startLine":10,"startCol":0,"endLine":18,"endCol":0},"title":"Short title for timeline","narration":"Brief, focused explanation of this specific code."}
say (narration only)
{"id":"e2","type":"say","title":"Transition","narration":"Now let's see how this is used in the routes."}
Users can add comments to any step while reviewing the trace. These comments are saved to the JSONL file as a comment field and represent feedback about the code shown in that step.
When Asked to Review a Trace
Always check for user comments. Comments tell you what the user wants changed in the code:
{"id":"e5","type":"highlightRange","filePath":"src/auth.ts","range":{"startLine":10,"endLine":18},"title":"Token validation","narration":"...","comment":"This should also check token expiration"}
This means: go to src/auth.ts lines 10-18 and add token expiration checking.
How to Handle Comments
Scan the trace for comment fields before making changes
Each comment is a code change request for the highlighted file/lines
Address the feedback by modifying the actual source code
After fixing, you may update or regenerate the trace to reflect changes
Example Comments and Actions
Comment on Step
Action in Code
"Add error handling here"
Add try/catch to the highlighted code
"This should be async"
Refactor the function to be async
"Missing null check"
Add validation for null/undefined
"Use the new API instead"
Update to use the newer API
Risk Annotations
Risks are explicitly specified by the agent in the trace to highlight steps that need reviewer attention.
When to Add Risks
Only add risks for steps that truly warrant attention:
security: Touches auth, encryption, user data, permissions
breaking-change: Changes public API, removes features
migration: Database schema changes
performance: Could impact performance significantly
Risk Syntax
{"id":"e1","type":"highlightRange","filePath":"src/auth/validate.ts","range":{"startLine":10,"startCol":0,"endLine":18,"endCol":0},"title":"Validate user token","narration":"This is where we validate the JWT token from the request.","risks":[{"category":"security","label":"User authentication logic"}]}
Only tag genuine risks that need reviewer attention
If you're unsure whether something is a risk, it probably isn't
Complete Example
Here's a well-structured trace for explaining a caching implementation:
{"id":"s1","type":"sectionStart","title":"Cache Interface","narration":""}
{"id":"e1","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":1,"startCol":0,"endLine":8,"endCol":0},"title":"Interface definition","narration":"The caching system is built around this simple interface."}
{"id":"e2","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":5,"startCol":0,"endLine":6,"endCol":0},"title":"Core methods","narration":"Get and set are your basic operations."}
{"id":"e3","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":7,"startCol":0,"endLine":8,"endCol":0},"title":"TTL parameter","narration":"The TTL parameter is what makes it interesting - every entry can have its own expiration."}
{"id":"s1-end","type":"sectionEnd","title":"","narration":""}
{"id":"s2","type":"sectionStart","title":"Memory Implementation","narration":""}
{"id":"e4","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":17,"startCol":0,"endLine":24,"endCol":0},"title":"Storage maps","narration":"Here's the in-memory implementation. This Map stores the values, and this second one tracks expiration times."}
{"id":"e5","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":28,"startCol":0,"endLine":35,"endCol":0},"title":"Get with TTL check","narration":"When you call get, we check the timestamp first and return undefined if it's stale."}
{"id":"e6","type":"highlightRange","filePath":"src/cache.ts","range":{"startLine":50,"startCol":0,"endLine":56,"endCol":0},"title":"Cleanup interval","narration":"The clever bit is this cleanup interval that removes expired entries every 60 seconds."}
{"id":"s2-end","type":"sectionEnd","title":"","narration":""}
{"id":"e7","type":"say","title":"Summary","narration":"That's the core caching layer - intentionally simple, just TTL-based expiration."}
Structuring a Walkthrough
Recommended Structure
Opening (say): Brief context about what we'll cover
Sections (sectionStart/sectionEnd): Group related concepts
2-5 highlightRange steps per section
Each step: one highlight, one focused explanation
Transitions (say): Connect sections naturally
Closing (say): Summarize key takeaways
Things to Avoid
Overloaded steps: If you're highlighting 20+ lines or writing a paragraph, split it up
Separate "open file" steps: Merge into highlightRange - the file opens automatically
Section announcements: Don't say "Now entering the Authentication section"
Over-explaining: Trust your audience to understand code basics
Orphan steps: Steps outside sections have longer pauses - group related ones
Checklist Before Generating
Each step highlights 2-6 lines (max 8-10 for tightly coupled code)
Functions are broken down: signature first, then body in chunks
Narration is 1-2 sentences per step
No "and then" in narration (split if needed)
Related steps are grouped in sections
Section nesting is max 2-3 levels deep with semantic parent-child relationships
Section events have empty narration
Natural, conversational language (not robotic)
Explanations focus on WHY, not just WHAT
Transitions connect sections naturally
IDs are unique and sequential (e1, e2, e3... or s1, s1-end for sections)
Risk annotations only on genuinely risky steps (security, breaking-change, migration, performance)
No metadata header needed — the extension handles highlight stability via snapshots
