---
name: assumption-led-debugging
description: Use when debugging bugs, failing tests, flaky behavior, build failures, integration problems, or confusing symptoms where guessing would be tempting.
---

# Assumption-Led Debugging

## Overview

Find the root cause before fixing. This combines Superpowers systematic debugging with Karpathy's bias toward surfacing assumptions, choosing simpler explanations first, and avoiding speculative edits.

## Workflow

1. Read the complete error, logs, stack trace, and failing assertion.
2. Reproduce or define what evidence would count as reproduction.
3. Write down the current assumptions and which ones are unverified.
4. Check recent changes, configuration, environment, and comparable working examples.
5. Trace the data or control flow backward from symptom to source.
6. Form one hypothesis at a time: "I think X because Y."
7. Test the hypothesis with the smallest diagnostic or code change.
8. Fix the root cause, then add or update a regression test when feasible.
9. Run fresh verification and report what passed or what still fails.

## Stop Conditions

Stop and ask or reframe when:

- The symptom is not reproducible and you need more data.
- Three attempted fixes have failed.
- The likely fix requires broad architecture changes.
- Multiple interpretations remain and choosing silently would risk the wrong behavior.

## What Not To Do

- Do not patch the symptom just to make the error disappear.
- Do not bundle several fixes into one experiment.
- Do not claim root cause from intuition alone.
- Do not refactor unrelated code while debugging.

## Output Pattern

Use concise evidence:

```text
Symptom: ...
Evidence gathered: ...
Hypothesis: ...
Fix: ...
Verification: ...
Remaining risk: ...
```