Produces a Debug Report documenting root cause, fix applied, and lessons learned through systematic hypothesis testing. Use when: 'debug this error', 'why is this failing', 'investigate the issue', 'find the root cause', 'fix this bug systematically'.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Produces a Debug Report documenting root cause, fix applied, and lessons learned through systematic hypothesis testing. Use when: 'debug this error', 'why is this failing', 'investigate the issue', 'find the root cause', 'fix this bug systematically'.
category
continuous-learning
triggers
["debug this error","why is this failing","investigate the issue","find the root cause","fix this bug systematically"]
tier
1
agents
["primary"]
tool_dependencies
["file_system"]
inputs
[{"name":"error_description","type":"string","description":"Description of the error or failing behavior to debug","required":true},{"name":"context","type":"string","description":"Additional context — stack traces, logs, reproduction steps","required":false}]
outputs
[{"name":"debug_report","type":"string","description":"Debug Report documenting root cause, fix applied, and lessons learned"}]
Debugging & Troubleshooting Skills
Version: 1.0
Created: 2026-02-02
Author: Cipher
Purpose: Systematic debugging and troubleshooting for code, systems, and workflows
Overview
This skill encodes best practices for debugging and troubleshooting—isolating problems, identifying root causes, and implementing fixes methodically. It provides patterns for reading logs, reproducing issues, testing hypotheses, and verifying solutions.
Philosophy: Debugging is systematic investigation, not random guessing. One change at a time, test, observe, learn.
If confirmed: Implement minimal fix, add error handling, add logging for future detection. If rejected: Move to next hypothesis, re-gather information, consider broader systemic causes.
Step 5: Verify & Document (5-10 minutes)
Verify: Original reproduction steps no longer fail, edge cases work, no regressions.
Document:
## Fix: [Issue Title]**Root Cause:** [What actually caused issue]
**Solution:** [What was fixed]
**Code Changes:** [File, function, or module changed]
**Testing:**- Original issue: Resolved
- Edge cases: Tested
- Regression check: No regressions
**Lessons Learned:** [What to do differently in future]
Common Debugging Patterns
Pattern 1: Read Logs Strategically
Don't read entire log files. Search for error codes or keywords, extract lines around error timestamp (±5 min), look for recurring patterns.
grep -i "error" app.log | tail -20
grep "2026-02-02T14:00" app.log -A 5 -B 5
grep -A 10 "Error:" app.log
Pattern 2: Use Logging to Verify
Point
Log What
Why
Before database query
Query string, parameters
See what's being executed
After database query
Rows returned, time taken
Performance check
Before API call
Request payload
Verify what's sent
After API call
Response status, body
Verify what's received
Before file write
File path, content
Verify what's written
When in doubt, add a log. You can always remove later.
Pattern 3: Binary Search for Root Cause
Narrow down variables systematically. For a slow query: test with 10 rows (rules out table size), then run EXPLAIN (reveals missing index), then add index and confirm fix. One variable at a time.
Pattern 4: Reproduce in Isolated Environment
When issue only happens in production: create minimal reproduction in dev, simplify data, mock external dependencies, test against same environment versions. Goal: isolate whether issue is data, code, or environment.
Pattern 5: Use Version Control for Time Travel
git log --oneline -10
git log --oneline --since="2026-02-02T13:00"
git bisect start
git bisect bad HEAD
git bisect good <last-working-commit>
Troubleshooting Categories
1. Code Errors (Runtime, Compile, Type)
Causes: Null/undefined access, async timing issues, type mismatches, module not found Approach: Read error carefully, check stack trace for file/line, search error code, isolate the function
Causes: Database out of sync, cache invalidation, race conditions, migration not applied Approach: Compare DB state vs. expected, check last sync timestamp, verify integrity, re-run sync or migration
4. Integration Failures
Causes: API contract mismatch, auth failures, network connectivity, service downtime Approach: Verify request format, check credentials, test API directly (curl/Postman), check service status
5. Environment-Specific Issues
Causes: Missing/wrong env vars, path differences (Win/Mac/Linux), dependency version conflicts, file permissions Approach: Compare working vs. broken env, check env vars, verify dependency versions, check paths and permissions
Quality Checklist
Before considering debugging complete:
Root cause identified (not just symptom fixed)
Hypothesis tested with evidence
Fix is minimal (don't over-engineer)
Original issue reproduced before fix
Fix resolves issue (not just hides it)
Edge cases tested
No regressions (other features still work)
Root cause, solution, and lessons learned documented
Common Pitfalls to Avoid
Shotgun debugging — Change everything — one change, test, observe
Scenario 1: "Debug this error: TypeError: Cannot read property 'id' of undefined" → Debug Report with hypothesis (null user object), test method (added logging), root cause confirmed, fix applied (null check), regression test documented
Scenario 2: "Why is this database query taking 8 seconds?" → Debug Report using binary search on query complexity, EXPLAIN output showing missing index, index added, before/after timing documented
Edge Cases
Error is intermittent (not reproducible): Add logging around the suspected area, capture the next occurrence, treat the log as the reproduction case
Issue only happens in production: Create a minimal reproduction in dev using production-equivalent data and environment vars; document the environment delta
Multiple simultaneous errors: Prioritize by severity — fix the error that is blocking other fixes first; do not debug all at once
Anti-Patterns
Changing multiple things at once before testing — makes it impossible to identify which change resolved the issue
Searching for the error message online before reading the stack trace — the stack trace almost always locates the cause; search is for when the trace is unhelpful
Marking a bug as fixed when tests pass but root cause was not confirmed — symptom masking produces the same bug later under different conditions
Writing a fix that hides the error (empty catch, fallback default) instead of addressing the cause
Related Skills:
workspace-navigation — When debugging collaborative workspaces
repo-context-sync — When debugging git integration issues
web-research — When searching error codes or similar issues online
research-modes — Deep investigation techniques
Last Updated: 2026-04-08
Maintained By: Cipher
Status: Active
