autoresearch:debug

autoresearch:debug — Scientific Bug Investigation

Root-cause analysis using the scientific method: form falsifiable hypotheses, design tests that could disprove them, eliminate candidates, and converge on confirmed root causes. Every step is logged — nothing is assumed, nothing is skipped.

Core Principle

A hypothesis is only useful if it can be falsified. "Something is wrong" is not a hypothesis. "The cache is returning stale data because the TTL is not being reset on write" is a hypothesis — it can be tested and disproved.

Output Structure

Create debug/ in the working directory (or alongside the failing artifact):

File	Purpose
debug/hypotheses.md	Active candidates under investigation
debug/eliminated.md	Ruled-out hypotheses with proof of elimination
debug/findings.md	Confirmed root causes with reproduction case

Initialize all three files before the first iteration.

---

Investigation Loop

Repeat until stop condition:

[Observe] --> [Hypothesize] --> [Design Test] --> [Run Test] --> [Update] --> [Log]
     ^                                                                          |
     |__________________________________________________________________________|

Stage 1 — Observe

Collect all available evidence before forming any hypothesis:

• Read error messages, stack traces, logs — verbatim, not paraphrased
• Identify: What is the symptom? When does it appear? When does it NOT appear?
• Identify: What changed recently? (git log, config changes, dependency updates)
• Identify: Is the bug deterministic or intermittent?

Write a symptom summary at the top of debug/findings.md:

## Symptom
[Exact error message or behavior]

## Observed conditions
- Occurs: [when/where]
- Does NOT occur: [contrasting case if known]
- First observed: [commit/date/event]

Stage 2 — Hypothesize

Form at least 2 candidate hypotheses before testing any of them. More candidates = less confirmation bias.