debugging-and-error-recovery

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

Updated Jul 9, 2026
One-click install
npx skills add https://github.com/assafmanor/waypoint --skill debugging-and-error-recovery-assafmanor
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debugging-and-error-recovery
Source: https://github.com/assafmanor/waypoint/tree/main/.claude/skills/debugging-and-error-recovery
Command: npx skills add https://github.com/assafmanor/waypoint --skill debugging-and-error-recovery-assafmanor

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 workflow that preserves evidence, reproduces the failure, and fixes the actual cause. ## Core Features & Use Cases - Six-Step Triage Checklist: Reproduce, localize, reduce, fix the root cause, guard with a regression test, and verify end-to-end. - Error-Specific Decision Trees: Dedicated triage flows for test failures, build failures, runtime errors, and non-reproducible bugs (timing, environment, or state dependent). - Safe Fallback Patterns: TypeScript snippets for graceful degradation, safe config defaults, and instrumentation guidelines for intermittent issues. - Use Case: A CI build fails after a refactor. Instead of guessing, you follow the checklist: reproduce locally, use git bisect to find the offending commit, reduce to a minimal failing case, fix the root cause, and add a regression test before resuming feature work. ## Quick Start Help me systematically debug this failing test and find its root cause instead of guessing at a fix.

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 a six-step triage: reproduce the failure reliably, localize which layer fails, reduce to a minimal failing case, fix the root cause rather than the symptom, add a regression test, then verify the full suite and build pass. Run the specific test in isolation first to rule out test pollution.

How to find which commit introduced a bug with git bisect?▼

Run git bisect start, mark the current commit as bad and a known working commit as good, then let git checkout midpoint commits while you run the failing test at each step. You can automate it with git bisect run followed by your test command.

What should I do when a bug cannot be reproduced?▼

Classify why it is non-reproducible: timing-dependent bugs need artificial delays and load, environment-dependent bugs need version and config comparison, and state-dependent bugs need isolation from shared state. If truly random, add defensive logging and monitor for recurrence.

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

Symptom fixes mask the underlying defect, so the bug resurfaces elsewhere and later changes build on broken behavior. Ask why the failure happens until you reach the actual cause, such as fixing a duplicating database 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 pushing past failures lets errors compound into later work. Stop, diagnose the flakiness source such as timing or order dependence, fix it, and only resume after verification passes.