hypothesis-debugging

majiayu000's avatarfrom majiayu000

Structured code debugging through hypothesis formation and falsification planning. Use when diagnosing bugs, unexpected behaviour, or system failures where the root cause is unclear. Produces a hypothesis document for execution by another agent rather than performing the investigation directly. Triggers on requests to debug issues, diagnose problems, investigate failures, or create debugging plans.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill provides a structured, scientific approach to code debugging through hypothesis formation and falsification planning. Based on Popperian principles, it helps engineers and AI agents diagnose complex system failures, unexpected behaviors, and elusive bugs by creating a rigorous roadmap of falsifiable tests to isolate root causes efficiently without falling into confirmation bias.

Use Cases

  • 1. Complex System Diagnosis: Identifying root causes in distributed systems or microservices where failures are intermittent and the origin is non-obvious.
  • 2. Automated Debugging Workflows: Generating structured instruction documents (debugging plans) that can be handed off to other specialized AI agents for execution and testing.
  • 3. Legacy Code Troubleshooting: Systematically ruling out environmental factors, state corruption, or logic errors in poorly documented or complex legacy codebases.
  • 4. Incident Response: Creating a logical trail of investigation during system outages to ensure all potential failure vectors are explored and tested in an ordered, efficient manner.
namehypothesis-debugging
descriptionStructured code debugging through hypothesis formation and falsification planning. Use when diagnosing bugs, unexpected behaviour, or system failures where the root cause is unclear. Produces a hypothesis document for execution by another agent rather than performing the investigation directly. Triggers on requests to debug issues, diagnose problems, investigate failures, or create debugging plans.

Hypothesis-Driven Debugging

Generate a structured debugging document that identifies candidate root causes and provides falsification plans for each. The output document instructs a separate execution agent; do not perform the investigation yourself.

Philosophical Foundation

Apply Popperian falsificationism: hypotheses cannot be proven true, only disproven. Design tests that could definitively rule out each hypothesis rather than confirm it. A good falsification test produces a clear negative result if the hypothesis is wrong.

Process

1. Gather Context

Before forming hypotheses, collect:

  • Symptom description: What behaviour is observed vs expected?
  • Reproduction conditions: When does it occur? Intermittent or consistent?
  • Recent changes: Deployments, configuration changes, dependency updates
  • Error artefacts: Stack traces, logs, error messages, screenshots
  • Environmental factors: OS, runtime versions, network conditions

If information is missing, note gaps in the output document.

2. Form Hypotheses

Generate 1–5 hypotheses ranked by plausibility. Each hypothesis must be:

  • Specific: Name the component, function, or interaction suspected
  • Falsifiable: A concrete test could disprove it
  • Independent: Falsifying one should not automatically falsify others

Common hypothesis categories:

Category Examples
State Race condition, stale cache, corrupted data
Input Malformed payload, encoding issue, boundary case
Environment Missing dependency, version mismatch, resource exhaustion
Logic Off-by-one, incorrect predicate, missing null check
Integration API contract violation, timeout, auth failure

Avoid vague hypotheses ("something wrong with the database"). Pin down the specific failure mode.

3. Design Falsification Plans

For each hypothesis, specify:

  1. Prediction: If this hypothesis is correct, what observable outcome follows?
  2. Falsification test: What action would produce a contradicting observation?
  3. Expected negative result: What outcome would disprove the hypothesis?
  4. Tooling required: Commands, scripts, or instrumentation needed
  5. Confidence impact: How decisively would a negative result rule this out?

Prefer tests that are:

  • Quick to execute
  • Minimally invasive
  • Deterministic rather than probabilistic

4. Output Document

Generate a Markdown document following the template in assets/debugging-plan.md. Save to the working directory as debugging-plan-{timestamp}.md.

Quality Criteria

A well-formed debugging plan exhibits:

  • Mutual exclusivity: At least one hypothesis should survive if others fail
  • Collective exhaustiveness: Hypotheses cover the likely failure space
  • Ordered efficiency: Cheapest decisive tests appear first
  • Clear success criteria: The executing agent knows when to stop

Anti-Patterns

  • Confirmation bias: Designing tests that can only succeed, not fail
  • Hypothesis creep: Adding new hypotheses during execution rather than revision
  • Coupling: Tests that cannot isolate individual hypotheses
  • Vagueness: "Check the logs" without specifying what pattern would falsify

References

  • references/examples.md: Worked examples of hypothesis-falsification pairs across common debugging scenarios (API timeouts, flaky tests, memory leaks)