debugging-test-failures

name	debugging-test-failures
description	Systematically investigates failing tests, distinguishes between test bugs and implementation bugs, and drives a fix with verification. Use when the user wants to debug failing tests.

Debugging Test Failures

Overview

This is the shared-skill replacement for the legacy Claude Code /debug:test workflow.

Use it when tests are failing and the goal is to identify the real root cause instead of making blind changes.

Read First

Before acting, read:

• .agents/skills/debugging-systematically/SKILL.md
• .claude/skills/test-driven-development/SKILL.md when the failing test is tied to new feature work or a bugfix

Core Workflow

1. Run the relevant test scope
   • one file or one pattern when possible
   • whole-suite only when needed
2. Parse the failure output
   • failing test names
   • expected vs actual behavior
   • error messages and stack traces
3. Read the failing test first
   • understand arrange / act / assert
   • explain what the test is trying to prove
4. Read the implementation under test
   • trace inputs, transformations, and outputs
5. Decide where the bug lives
   • implementation
   • test logic
   • mock/setup
   • broader shared root cause
6. Apply a minimal fix
   • fix the real problem, not just the symptom
7. Re-run verification
   • the failing test
   • nearby tests when relevant

Decision Heuristics

• Prefer implementation fixes when the test encodes correct expected behavior.
• Prefer test fixes when the implementation is correct and the test is asserting the wrong thing.
• If multiple failures share one cause, fix the root cause before touching individual assertions.
• If the test never demonstrated a correct RED state, repair the test before trusting it.

Cross-Agent Rules

• Treat this skill as the portable replacement for /debug:test.
• Keep a short execution plan, but do not depend on a tool-specific todo API.
• Ask bounded clarification only if multiple failure scopes or fix strategies are materially different.
• Always end with real verification, not reasoning alone.