debugging-and-error-recovery

Diagnose test failures, build errors, and runtime bugs through structured root-cause triage.

Updated Jun 8, 2026
One-click install
npx skills add https://github.com/Avistian/nba --skill debugging-and-error-recovery-avistian
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debugging-and-error-recovery
Source: https://github.com/Avistian/nba/tree/main/.cursor/skills/debugging-and-error-recovery
Command: npx skills add https://github.com/Avistian/nba --skill debugging-and-error-recovery-avistian

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When tests fail, builds break, or runtime behavior goes wrong, developers often guess at fixes or patch symptoms instead of root causes, wasting hours and letting bugs compound. This Skill enforces a disciplined stop-the-line debugging process that preserves evidence, localizes the failure, and fixes the actual cause. ## Core Features & Use Cases - Structured Triage Checklist: A six-step ordered process (reproduce, localize, reduce, fix root cause, guard, verify) with decision trees for test failures, build errors, and runtime bugs. - Non-Reproducible Bug Strategies: Concrete tactics for timing-dependent, environment-dependent, and state-dependent failures, including git bisect workflows for regression hunting. - Regression Guarding & Safe Fallbacks: Patterns for writing regression tests, graceful degradation, safe config defaults, and instrumentation guidelines that distinguish temporary logging from permanent monitoring. - Use Case: A CI pipeline fails after a refactor. Instead of guessing, follow the triage checklist to reproduce locally, bisect to the offending commit, reduce to a minimal failing case, fix the root cause, and add a regression test before resuming feature work. ## Quick Start Ask the assistant to systematically debug the failing test or error you are seeing and find its root cause instead of guessing.

Frequently Asked Questions about debugging-and-error-recovery

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a failing test systematically?▼

Follow an ordered triage process: reproduce the failure reliably, localize which layer is failing, reduce to a minimal failing case, fix the root cause, add a regression test, then verify the full suite passes. Avoid guessing or skipping steps.

How to find which commit introduced a bug?▼

Use git bisect: mark the current commit as bad and a known-working commit as good, then git checks out midpoint commits for you to test. You can automate it with git bisect run followed by your test command.

What should I do when a bug is not reproducible?▼

Classify it as timing-dependent, environment-dependent, or state-dependent. Add timestamps or artificial delays for race conditions, compare environments and data for environment issues, and check for leaked shared state between tests or requests.

Why is fixing symptoms instead of root causes a problem?▼

Symptom fixes mask the underlying issue, which resurfaces elsewhere and compounds with later changes. Ask why the failure happens until you reach the actual cause, such as fixing a duplicating JOIN query rather than deduplicating in the UI.

Should I skip a flaky test to keep working on features?▼

No. Flaky tests mask real bugs and errors compound when you build on top of failures. Stop feature work, diagnose the flakiness source such as timing or order dependence, and fix it before resuming.

When should debugging instrumentation be removed?▼

Remove temporary logging once the bug is fixed and a regression test guards against recurrence, especially if it contains sensitive data. Keep permanent instrumentation like error boundaries, API error logging, and performance metrics at key flows.