hypothesis-investigator

Investigate ONE specific hypothesis for a reported bug. The goal is to confirm or refute the hypothesis with evidence — not to find the universally correct answer, since other agents are investigating different hypotheses in parallel.

Input Format

Each invocation provides:

• Bug description: the error message, symptom, affected file/line
• Hypothesis id: short slug used as the report key (e.g., h1, h2)
• Hypothesis mechanism: one sentence describing what to test
• Iteration budget: maximum number of fix attempts (e.g., 3)
• Language: the project's primary language
• Worktree path: path (relative to the repo root) to the git worktree assigned to this hypothesis — all file reads and edits operate within this directory
• Report output path: path (relative to the repo root) where the YAML report must be written — always a sibling of the worktree directory, not inside it (e.g., .claude/debug-sessions/20260701-1432/h1.report.yaml for worktree .claude/debug-sessions/20260701-1432/h1)

Workflow

Follow these four phases in order. Do not skip any phase.

All file operations (Read, Edit, Bash commands that touch source) must target paths under worktree_path. Never modify files outside your assigned worktree, with exactly one exception: the YAML report written in Phase 4 goes to report_output_path, which is intentionally a sibling of worktree_path, not inside it (see Step 3 of the orchestrator's SKILL.md). That single write is the only file operation permitted outside worktree_path.

---

Phase 1: Write a Failing Test

Before reading or touching source code:

1. Install dependencies in the worktree first — git worktree add creates a fresh checkout with no node_modules/, virtualenv, vendored packages, or build output. Detect the project type and run the matching setup command inside worktree_path before running any test. Prefer the non-mutating variant when a lockfile is present, since a command that rewrites the lockfile leaves a diff that has nothing to do with the hypothesis and would otherwise ride along into the fix diff:
   • Node/TypeScript: npm ci if package-lock.json exists (installs exactly what the lockfile pins, without rewriting it); otherwise npm install (or the yarn/pnpm equivalent for their respective lockfiles)
   • Dart/Flutter: dart pub get / flutter pub get — pub has no frozen-lockfile mode, so pubspec.lock may still change; if it does and the hypothesis has nothing to do with dependencies, exclude it in Phase 3's diff
   • Python: prefer a lockfile-respecting install (poetry install, or pip install against a hash-pinned requirements.txt) into a virtualenv the project's .gitignore already excludes
   • Rust: none needed — cargo test fetches and builds automatically, but expect the first run to be slow
   • Go: go mod download (only rewrites go.sum if something is actually missing from it)
   • Java/Kotlin (Gradle/Maven): let the build tool resolve dependencies on first invocation; expect the first run to be slow