debugging-and-error-recovery
Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.
Author
Category
Development ToolsInstall
Download and extract to your skills directory
Copy command and send to AI Agent for auto-install:
Debugging and Error Recovery
Skill Overview
Provides a systematic root-cause debugging methodology. Through structured checklists and stop-the-line rules, it helps developers identify and fix root causes in test failures, build interruptions, runtime exceptions, and production incidents, rather than wasting time guessing.
Applicable Scenarios
1. Test Failures or Build Interruptions
When tests fail after code changes, CI builds report errors, or type errors and dependency issues occur, use the six-step checklist—from reproduction and localization to simplification, root-cause fixing, and verification—to avoid continuing development while skipping the problem and allowing errors to accumulate.
2. Abnormal Runtime Behavior
When an application encounters a TypeError, network error, rendering crash, blank screen, or intermittent bug, follow a layered troubleshooting process (frontend/backend/database/external services) to locate the problem, and use tools such as Git Bisect to identify the specific commit that introduced it.
3. Production Incidents and Bug Reports
When users report bugs or online errors occur, first ensure service availability through degraded and safe fallback modes. Then use a systematic approach to reproduce, locate, and fix the root cause, add regression tests to prevent recurrence, and finally validate the entire scenario end to end.
Core Features
1. Six-Step Structured Debugging Process
Provides a checklist that must not be skipped: reproduce the problem, locate the faulty layer, create a minimal reproduction case, fix the root cause rather than the symptom, write a regression test to prevent recurrence, and verify the fix end to end. This process applies to various problem scenarios, including test failures, build errors, runtime exceptions, and production incidents.
2. Troubleshooting Strategies for Irreproducible Problems
For intermittent bugs, provides categorized approaches for time-dependent, environment-dependent, state-dependent, and genuinely random issues: add timestamped logs, use artificial delays to widen race-condition windows, compare environmental differences, check for state leakage, and set up error alerts and monitoring. These methods help developers narrow down the scope and monitor the problem even when it cannot be reliably reproduced.
3. Error Classification and Handling Patterns
Provides dedicated decision trees for test failures, build failures, and runtime errors: determine whether related code was changed, whether the test itself is at fault, or whether side effects caused shared-state contamination. It also provides specific troubleshooting paths for TypeErrors, network errors, rendering errors, and abnormal behavior without error messages, avoiding blind guesswork.
Frequently Asked Questions
When should the stop-the-line rule be used?
Whenever anything unexpected occurs—tests fail, a build is interrupted, errors appear in the logs, or previously working functionality stops working—you should immediately stop the line. The stop-the-line rule requires you to stop adding new features, preserve evidence (error output, logs, and reproduction steps), use the checklist to diagnose the issue, fix the root cause, add protective tests, and resume only after verification. Do not skip failing tests and continue development, as errors will accumulate.
How can an irreproducible bug be reproduced?
First determine why it cannot be reproduced:
What is the difference between fixing a symptom and fixing the root cause?
A symptom fix addresses only the visible behavior without resolving the underlying cause, making recurrence likely. For example, if a user list displays duplicates, a symptom fix would deduplicate the entries in the UI component; a root-cause fix would identify a JOIN issue in the API query, add DISTINCT, or fix the data model. During debugging, continually ask “Why is this happening?” until the true cause is found, rather than merely patching the surface manifestation. After fixing the issue, add a regression test to ensure it does not happen again.