Debugging

Debug problems systematically with structured hypothesis-driven analysis. This workflow prevents the common trap of guessing at fixes and instead follows a disciplined process: reproduce, hypothesize, isolate, fix, verify.

When to Use This

• A test is failing unexpectedly.
• A bug has been reported and you need to find the root cause.
• Something worked before and now it does not, and you are not sure why.
• You are getting an error message that you do not understand.

What You'll Use

Walkthrough

Scenario: A test is failing unexpectedly after a dependency update.

Step 1: Describe the Problem

Tell Claude about the failure:

"The test_user_preferences_update test is failing after we updated the ORM library. It was passing before the update."

The systematic-debugging skill activates automatically. Claude does not propose a fix immediately.

Step 2: Reproduce

Claude first verifies the failure is reproducible:

• Runs the failing test to confirm the error
• Reads the full error output and stack trace
• Checks if other related tests are also failing

Step 3: Form Hypotheses

Based on the error, Claude generates ranked hypotheses:

1. Breaking API change — The ORM update changed the upsert method signature.
2. Schema mismatch — The test database schema is out of date.
3. Fixture issue — Test fixtures use deprecated field names.

Each hypothesis includes what evidence would confirm or rule it out.

Step 4: Isolate

Claude systematically tests each hypothesis:

• Reads the ORM changelog for breaking changes (hypothesis 1)
• Checks the migration state of the test database (hypothesis 2)
• Inspects the test fixtures (hypothesis 3)

Evidence is collected and hypotheses are updated. In this scenario, the ORM changelog confirms a signature change in the upsert method.

Step 5: Fix with TDD

Once the root cause is identified, the test-driven-development skill takes over:

1. Write a focused test — A test that specifically targets the broken behavior with the new API.
2. Confirm it fails — The test fails, confirming the root cause.
3. Apply the fix — Update the repository code to use the new upsert signature.
4. Verify — Run the focused test (passes), then run all tests (all pass).

Step 6: Verification

The verification-before-completion skill checks:

• The original failing test passes
• No other tests were broken by the fix
• The fix is minimal and targeted (no scope creep)

Quick Reference

Tips

• The systematic-debugging skill activates automatically when you describe a bug or failure. You do not need to invoke a command.
• Do not suggest a fix before Claude has finished diagnosis. The skill is designed to prevent premature fixes.
• Claude collects evidence at each step. If the first hypothesis is wrong, it moves to the next one with updated evidence.
• For complex bugs, Claude may use the serena MCP server (semantic code analysis) to trace call paths and find where behavior diverges.
• After fixing a bug, consider whether the root cause could affect other parts of the codebase. Claude often suggests related areas to check.

See Also

• superpowers plugin — Full plugin documentation
• Implementing workflow — TDD implementation approach
• Code Review workflow — Review code for bugs proactively