Systematic debugging

Skill muyen/vibe-to-prod/.claude/skills/systematic-debugging

Systematic debugging with 4-phase root cause analysis. Triggers when bugs are reported, errors encountered, or unexpected behavior observed.From its SKILL.md

Install

npx -y skills add muyen/vibe-to-prod --skill systematic-debugging

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

3.0 KB, as published. Nobody here has run it

Systematic Debugging Skill

Apply structured 4-phase debugging to find root causes, not just symptoms.

When to Activate

This skill should activate when:

User reports a bug or unexpected behavior
Error messages or stack traces appear
Tests are failing
User says "fix", "debug", "broken", "not working", "issue"
Behavior differs from expected

4-Phase Debugging Process

Phase 1: REPRODUCE

Before fixing anything:
1. Understand the expected behavior
2. Understand the actual behavior
3. Find reliable reproduction steps
4. Identify the exact error/symptom

Questions to answer:

What should happen?
What actually happens?
Can I reproduce it consistently?
What are the exact steps?

Phase 2: ISOLATE

Narrow down the problem:
1. Find the smallest reproduction case
2. Identify which component/layer fails
3. Check recent changes (git log, git diff)
4. Add logging/debugging to trace execution

Techniques:

Binary search through code changes
Add strategic logging
Comment out code sections
Test with minimal input

Phase 3: IDENTIFY ROOT CAUSE

Find the actual cause, not symptoms:
1. Follow the data flow
2. Check assumptions
3. Verify inputs/outputs at each step
4. Ask "why" 5 times

Common root causes:

Symptom	Likely Root Cause
404 on API	Route not registered
Type mismatch	Wrong type conversion
Null pointer	Uninitialized variable
Race condition	Missing synchronization
Auth failure	Token/session expired

Phase 4: FIX AND VERIFY

Fix properly:
1. Write a test that reproduces the bug
2. Implement the fix
3. Verify the test passes
4. Check for similar issues elsewhere
5. Prevent regression

Debugging Commands

Backend (Go)

# Run with verbose logging
go run ./cmd/api/main.go

# Run specific test with verbose output
go test -v -run TestName ./...

# Add debug logging
zap.L().Debug("checkpoint", zap.Any("data", data))

iOS (Swift)

// Debug print (visible in Xcode console)
#if DEBUG
print("DEBUG: \(variable)")
#endif

Android (Kotlin)

// Debug logging
Log.d("TAG", "Debug: $variable")

Process

Don't guess - Reproduce first
Don't fix symptoms - Find root cause
Verify assumptions - Check each step
Test the fix - Write regression test
Check for similar issues - Fix all instances

Output Format

## Bug Analysis

**Symptom**: [what user reported]
**Reproduction**: [steps to reproduce]

### Investigation
- [ ] Reproduced: [yes/no]
- [ ] Isolated to: [component/file]
- [ ] Root cause: [actual cause]

### Fix
- **File**: [file:line]
- **Change**: [what was changed]
- **Test**: [test that prevents regression]

### Verification
- [ ] Original issue fixed
- [ ] No new issues introduced
- [ ] Similar code checked