| name | debug-video |
| description | Video-based visual debugging — extract key frames from screen recordings and analyze UI bugs over time. Detects animation glitches, race conditions, gesture issues, scroll jank, keyboard overlap, and navigation transitions that screenshots cannot capture. |
/debug-video — Video Visual Debugging
You are executing the /debug-video command. Extract key frames from a video recording and use the visual-debugger agent for temporal UI analysis.
Arguments
/debug-video <video-file> — analyze a screen recording
/debug-video <video-file> --max-frames 15 — limit extracted frames (default: 20)
/debug-video <video-file> --description "button disappears after tap" — with context
Supported Formats
All video formats supported: .mp4, .mov, .webm, .avi, .mkv, .gif
Process
Step 1: Extract Key Frames
Run the frame extractor:
node scripts/extract-video-frames.js "<video-path>" --max-frames 20
This outputs JSON with frame paths. If ffmpeg is not found, show the user install instructions from the error output.
Duration guidance:
- ≤ 30 seconds: optimal, full detail analysis
- 30-60 seconds: key moments only, still effective
-
60 seconds: warn user to trim to the relevant section
Step 2: Read All Extracted Frames
Read EVERY extracted frame image file using the Read tool. The frames are ordered chronologically — frame_001 is earliest, frame_N is latest.
Step 3: Temporal Analysis
Analyze the frames as a timeline, not individual screenshots. Look for:
| Category | What to Look For |
|---|
| Animation bugs | Element position/size changes unexpectedly between frames |
| Race conditions | Loading → content → loading again, or flash of wrong content |
| Gesture issues | Drag/swipe stuck mid-motion, element not following finger |
| Scroll jank | Content jumping, blank areas during scroll, inconsistent spacing |
| Keyboard overlap | Input hidden behind keyboard after tap sequence |
| Navigation glitches | Flash of wrong screen, transition tearing, double-render |
| Layout shifts | Content moving/resizing after data loads |
| State bugs | UI showing stale data, toggle not reflecting state |
| Disappearing elements | Element visible in frame N, gone in frame N+1 |
| Z-index issues | Element appearing behind/above where it shouldn't |
Present findings with frame references:
Frame 3→4: Button "Submit" shifts 20px down after keyboard appears
Frame 6→7: Loading spinner reappears after content was already visible (race condition)
Frame 9: Bottom tab bar overlaps with input field
Step 4: Identify Source Components
For each temporal issue found:
- Identify which component/screen is affected
- Read the source file
- Determine the root cause (missing layout animation, useEffect race, keyboard avoidance, etc.)
Step 5: Interactive Fix
Same as /debug-visual:
- User picks issue numbers to fix
- Apply minimal fix in source
- Ask user to record a new video to verify
Step 6: Summary
Output
## Video Debug Report
### Video Info
- File: [path]
- Duration: [X seconds]
- Frames analyzed: [N key frames]
### Timeline Analysis
| Frames | Issue | Category | Severity |
| ------ | ---------------------------------------------- | ---------------- | -------- |
| 3→4 | Submit button shifts down on keyboard open | Layout | Major |
| 6→7 | Loading spinner reappears after content loaded | Race condition | Critical |
| 9 | Tab bar overlaps input field | Keyboard overlap | Major |
### Issue Details
**Issue 1 (Frame 3→4): Button shifts on keyboard open**
- Component: `LoginScreen.tsx`
- Root cause: Missing `KeyboardAvoidingView` wrapper
- Fix: Wrap form in `<KeyboardAvoidingView behavior="padding">`
**Issue 2 (Frame 6→7): Loading spinner race condition**
- Component: `FeedScreen.tsx`
- Root cause: `useEffect` fetches data but component unmounts/remounts during tab switch
- Fix: Add cleanup to useEffect, check mounted state before setState
### Recommended Fixes
1. [Priority order with code changes]
### Which issues should I fix? (reply with numbers)
What Video Analysis Catches That Screenshots Miss
- Timing-dependent bugs — things that only happen during transitions
- Animation correctness — is the animation smooth or does it jump?
- User flow bugs — sequences of actions that produce incorrect states
- Performance visual artifacts — dropped frames, jank, flash of unstyled content
- Keyboard interaction — the full sequence of keyboard appearing and content adjusting
