ReddRadar
Agent skill
systematic-debugging
Systematic 4-phase debugging process for finding root causes
Install this agent skill to your Project
npx add-skill https://github.com/48Nauts-Operator/opencode-baseline/tree/main/.opencode/skill/systematic-debugging
Metadata
Additional technical details for this skill
- audience
- developers
- workflow
- debugging
SKILL.md
What I Do
- Guide systematic root cause analysis
- Prevent shotgun debugging (random changes hoping something works)
- Document findings for future reference
- Ensure fixes actually solve the problem
When to Use Me
Use this skill when:
- Encountering unexpected behavior
- Tests are failing
- Production issues need investigation
- After 2+ failed fix attempts
The 4-Phase Process
Phase 1: REPRODUCE
Goal: Reliably trigger the bug
1. Get exact steps to reproduce
2. Identify the minimal reproduction case
3. Document environment details (OS, versions, config)
4. Create a failing test if possible
Questions to answer:
- Can you reproduce it consistently?
- What's the minimum setup needed?
- Does it happen in all environments?
Phase 2: ISOLATE
Goal: Narrow down the location
1. Binary search through the codebase
2. Add strategic logging/breakpoints
3. Check recent changes (git blame, git bisect)
4. Eliminate possibilities systematically
Techniques:
git bisect- Find the commit that introduced the bug- Comment out code sections
- Add assertions to verify assumptions
- Check input/output at each step
Phase 3: IDENTIFY
Goal: Find the root cause (not just symptoms)
1. Understand WHY it's happening, not just WHAT
2. Trace the data flow
3. Check assumptions about state
4. Look for edge cases
Common root causes:
- Incorrect assumptions about input
- Race conditions
- State mutation
- Off-by-one errors
- Null/undefined handling
- Type coercion issues
Phase 4: FIX & VERIFY
Goal: Fix minimally and prove it works
1. Write a failing test that reproduces the bug
2. Make the minimal fix
3. Run the test - it must pass
4. Run full test suite - no regressions
5. Document the fix
Rules:
- Fix ONE thing at a time
- Don't refactor while fixing
- Verify the fix actually solves the reported issue
- Add tests to prevent regression
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Shotgun debugging | Random changes, unclear if fixed | Follow the 4 phases |
| Fixing symptoms | Bug returns later | Find root cause |
| Changing multiple things | Can't tell what fixed it | One change at a time |
| No reproduction test | Bug can return | Always add a test |
| Skipping verification | Fix may be incomplete | Test thoroughly |
When to Escalate
After 3 failed fix attempts:
- STOP further changes
- Document what you've tried
- Revert to last known working state
- Ask for help with full context
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
48Nauts-Operator/opencode-baseline
file-organizer
Organize files and folders intelligently with duplicate detection
48Nauts-Operator/opencode-baseline
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.
48Nauts-Operator/opencode-baseline
auth-implementation-patterns
Master authentication and authorization patterns including JWT, OAuth2, session management, and RBAC to build secure, scalable access control systems. Use when implementing auth systems, securing APIs, or debugging security issues.
48Nauts-Operator/opencode-baseline
sql-optimization-patterns
Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database schemas, or optimizing application performance.
48Nauts-Operator/opencode-baseline
monorepo-management
Master monorepo management with Turborepo, Nx, and pnpm workspaces to build efficient, scalable multi-package repositories with optimized builds and dependency management. Use when setting up monorepos, optimizing builds, or managing shared dependencies.
48Nauts-Operator/opencode-baseline
git-advanced-workflows
Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog to maintain clean history and recover from any situation. Use when managing complex Git histories, collaborating on feature branches, or troubleshooting repository issues.
Didn't find tool you were looking for?