/debug-investigator

name: debug-investigator
description: 'Hypothesis-driven debugging with ranked hypotheses, git bisect strategy, instrumentation planning, and minimal reproduction design. Triggers on: "debug this systematically", "root cause analysis", "bisect this bug", "rank hypotheses", "isolate this issue", "minimal reproduction". NOT for general reasoning.'
metadata:
  version: 1.1.1
  category: development
  tags: [debugging, root-cause, hypothesis, bisect]
  difficulty: intermediate
  phase: build

Debug Investigator

Structured debugging methodology that replaces ad-hoc exploration with hypothesis-driven investigation. Captures symptoms, builds a deterministic feedback loop, analyzes evidence (stacktraces, logs, state), generates ranked hypotheses, designs bisection strategies, identifies instrumentation points, and produces minimal reproductions — documenting every step so dead ends are never revisited.

> **When to use this skill vs native debugging:** The base model handles straightforward > debugging (clear stacktraces, obvious errors) natively. Use this skill for non-obvious bugs > requiring systematic investigation: intermittent failures, bugs with no clear stacktrace, > performance regressions, or issues requiring git bisection and hypothesis ranking.

Reference Files

| File | Contents | Load When | | -------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------- | | `references/stacktrace-patterns.md` | Exception taxonomy, traceback reading, common Python/JS error signatures | Stacktrace or exception present | | `references/hypothesis-templates.md` | Bug category catalog, probability ranking, confirmation/refutation tests | Always | | `references/bisection-guide.md` | git bisect workflow, binary search debugging, narrowing techniques | Bug appeared after a change | | `references/log-analysis.md` | Log pattern extraction, anomaly detection, timeline correlation | Log output available | | `references/instrumentation-points.md` | Strategic logging placement, breakpoint strategy, state inspection techniques | Investigation plan needed |

Prerequisites

• **git** — for bisection and history analysis
• **Access to source code** — cannot debug opaque binaries
• **Reproducible environment** — or at minimum, error output (stacktrace, logs)

Project Context

Before deep investigation, check for repo-local agent context:

• `docs/agents/domain.md` for `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR lookup rules
• `CONTEXT.md` or relevant context-local glossary for domain vocabulary
• `docs/adr/` and context-local ADRs for decisions near the failing area

Use the project glossary in hypotheses, repro names, and prevention recommendations. If the repo lacks these files, continue normally; do not block debugging on context setup.

Workflow

Phase 1: Symptom Capture

Before touching code, document the observable problem:

1. **What is happening?** — Describe the observed behavior precisely. "It crashes" is insufficient. "Raises `KeyError('user_id')` on line 42 of `auth.py` when calling `get_current_user()` with a valid session token" is actionable. 2. **What should happen?** — Define the expected behavior. If unknown, state that. 3. **Reproducibility** — Always, intermittent (with frequency), or one-time? Intermittent bugs require different strategies than deterministic ones. 4. **Recency** — When did this start? Correlate with recent changes: `git log --oneline -20`. If the bug appeared after a specific commit, bisection is the fastest path. 5. **Environment** — Python version, OS, dependency versions, configuration differences between working and broken environments.

Phase 2: Build a Feedback Loop

Create a fast, deterministic pass/fail signal for the reported bug before ranking hypotheses or changing production code. The loop must reproduce the user's symptom, not a nearby failure.

Try these seams in order:

1. Failing test at the smallest public interface that reaches the bug. 2. CLI or script invocation with fixture input and asserted output. 3. Curl or HTTP request against a local server with asserted response, logs, or state. 4. Browser automation for UI bugs with DOM, console, and network assertions. 5. Replayed trace, event payload, HAR, or log fixture through the real code path. 6. Throwaway harness that boots the minimal subsystem needed to trigger the path. 7. Property, fuzz, or stress loop for intermittent failures. 8. `git bisect run` harness when the bug appeared between known good and bad revisions.

Improve the loop before moving on:

• Make it faster by narrowing setup and caching expensive fixtures.
• Make it sharper by asserting the exact symptom.
• Make it more deterministic by pinning time, seeds, filesystem paths, and network access.
• For intermittent bugs, raise reproduction rate with repeated runs, concurrency, stress, or

timing probes until the failure is frequent enough to debug.

If no credible loop can be built, stop and state what was tried. Request the missing artifact: environment access, captured payloads, logs, screen recording with timestamps, or permission for temporary instrumentation. Do not proceed to speculative fixes.

Phase 3: Evidence Analysis

Examine all available evidence before forming hypotheses:

1. **Stacktrace interpretation** — If a traceback exists, read it bottom-up. The last frame is where the error manifested, but the cause is often several frames up. Identify:

• Exception type and message
• The frame where the error originated vs. where it was raised
• Any familiar patterns (see `references/stacktrace-patterns.md`)

2. **Log pattern extraction** — Search logs for:

• Temporal