debug-failing-test

SKILL.md

---
name: debug-failing-test
description: Run a failing test, read its trace, locate and fix the real root cause in the source (not the test), then re-run until green. Detects the runner (vitest/jest/pytest/go test/swift test/cargo test). Use when a test or test command is failing, a CI check is red, or you need to diagnose and fix a broken spec without weakening it.
allowed-tools: [read_file, edit_file, write_file, list_files, search_code, execute_command]
triggers: ["test is failing", "fix the failing test", "debug this test", "tests are red", "make the test pass"]
version: 1.0.0
author: Codeep
---

You fix the CODE that a test exposes as broken. Never weaken, skip, or delete a test to make it pass. If the test itself is genuinely wrong, say so explicitly and explain before changing it.

## Detect the runner
If the user gave an exact command, use it. Otherwise infer from the project:
- `package.json` has vitest → `npx vitest run <file>`; has jest → `npx jest <file>`. Honor any `scripts.test`.
- `pytest.ini`/`pyproject.toml`/`setup.cfg` or `test_*.py` → `pytest <file>::<test> -x`
- `go.mod` → `go test ./... -run <TestName> -v`
- `Package.swift` → `swift test --filter <TestName>` (macOS)
- `Cargo.toml` → `cargo test <test_name> -- --nocapture`
Use `list_files` / `read_file` to confirm before running. Prefer running the single failing test for speed.

## Steps
1. Reproduce: run the failing test via `execute_command`. Capture the FULL output (assertion message, expected vs actual, file:line, stack).
2. Read the test with `read_file` to learn the intended behavior and exact assertion.
3. Trace to source: from the top non-test frame, open the implementation. Use `search_code` to follow the failing symbol/function across files.
4. Form a hypothesis for the ROOT CAUSE (off-by-one, wrong default, null path, bad async/await, stale mock, type coercion, timezone, etc.). State it in one sentence.
5. Fix the source with `edit_file` (smallest change that addresses the cause, not the symptom). Only touch the test if it asserts genuinely incorrect behavior — and flag that.
6. Re-run the same command. If green, run the broader suite (`scripts.test`, `pytest`, `go test ./...`, `cargo test`, `swift test`) to catch regressions.
7. Repeat 1-6 until green. Stop after 4 fix attempts on the same test and report what you tried.

## On failure
- Same error after a fix → your hypothesis is wrong; re-read the trace, add a targeted log/print or assert, re-run, then remove the probe.
- Flaky (passes sometimes) → suspect async ordering, shared state, time/random, or test isolation; don't "fix" by retrying.
- Can't reproduce → confirm runner, node/python/toolchain version, env vars, and that deps are installed (`npm ci`, `pip install -e .`, etc.).
- Cascade of new failures → you fixed the symptom or broke a contract; revert and reconsider.

## Notes
- Determinism over hacks: never add `sleep`, blanket try/except, `.skip`, `xfail`, loosened matchers, or snapshot overwrites to force green.
- Keep the diff minimal and explain the root cause in your final summary (file:line + why it failed + the fix).
- Done when: the originally-failing test passes AND the full suite is green, with the test's intent intact.