Agentic root cause analysis through hypothesis-driven debugging

dilagent automates the tedious process of reproducing, diagnosing, and fixing bugs through systematic hypothesis testing and experimentation. It combines LLM agents with structured scientific methodology to identify root causes and validate fixes.

Ideal for:

• Complex, hard-to-reproduce bugs (race conditions, timing issues)
• Performance regressions without obvious cause
• Issues that occur only in specific environments
• Bugs with multiple potential root causes
• Intermittent or flaky test failures

Not suitable for:

• Simple syntax errors or compilation issues
• Obvious logic errors that are easily spotted
• Issues with clear error messages pointing to the problem

dilagent follows a structured, multi-stage approach to debugging:

First, dilagent attempts to reproduce the issue:

• Creates minimal reproducible test cases (repro.ts)
• Measures timing characteristics (performance, timeouts, race conditions)
• Documents setup requirements
• Asks clarifying questions when needed

Based on successful reproduction, dilagent generates targeted hypotheses:

• Analyzes reproduction data and codebase context
• Creates multiple hypotheses (H001, H002, H003...)
• Tailors hypotheses to the type of issue (performance, concurrency, logic)
• Outputs structured hypotheses.json for tracking

Each hypothesis is tested in parallel:

• Independent testing in isolated worktrees
• Each hypothesis can result in:
  • ✅ Proven: Root cause identified
  • ❌ Disproven: Not the issue, move on
  • ❓ Inconclusive: Requires additional data
• Counter-experiments validate findings

For complex issues requiring human insight:

• REPL-based interactive debugging session
• Agent-assisted exploration with full context
• Direct manipulation and testing

The process continues iteratively until the root cause is found and validated.

• Automated Reproduction: Generates minimal test cases from bug reports
• Parallel Hypothesis Testing: Tests multiple theories simultaneously in isolated environments
• Counter-Experiment Validation: Prevents false positives through negative testing
• Interactive Fallback: REPL mode for complex cases requiring human expertise
• Evidence-Based: Every conclusion backed by reproducible experiments
• MCP Integration: Leverages Model Context Protocol for tool orchestration

dilagent manager setup --working-directory ./debug-session --context-directory ./my-project

• Creates .dilagent/ directory structure
• Generates context.md with codebase information and issue description

dilagent manager repro --working-directory ./debug-session --llm claude

• Creates reproduction.md with steps to reproduce the issue
• Generates diagnostic information and error details

dilagent manager generate-hypotheses --working-directory ./debug-session --hypothesis-count 3 --llm claude

• Creates numbered hypothesis directories: H001-config-issue/, H002-race-condition/, etc.
• Each contains:
  • hypothesis.md - The specific theory about the bug
  • instructions.md - Steps to test the hypothesis

dilagent manager run-hypotheses --working-directory ./debug-session --llm claude

• Creates git worktrees for parallel testing (e.g., worktree-H001-config-issue/)
• AI agents test each hypothesis independently
• Updates report.md in each hypothesis directory with findings
• Logs stored in .dilagent/H{NNN}-{slug}/hypothesis.log

# Hypothesis H003: Race Condition in Connection Pool

## Status: ✅ PROVEN

## Initial Analysis
The intermittent timeout errors in production suggested a potential race condition
in the database connection pool management. The error pattern showed:
- Errors occur only under high concurrent load (>100 req/s)  
- Error rate increases exponentially with load
- Database logs show connection pool exhaustion messages
- Issue started appearing after the connection pooling refactor in commit abc123

## Investigation Steps

### Step 1: Reproduce the Issue
Created load test script that successfully reproduced the issue:
```bash
# Load test that triggers the race condition
ab -n 10000 -c 50 http://localhost:3000/api/users/search
# Result: 3.2% failure rate with "connection pool timeout" errors

// PROBLEMATIC: Race condition between check and increment
if (this.activeConnections < this.maxConnections) {
  // Gap here - another request could increment activeConnections
  this.activeConnections++;
  return this.createConnection();
}

// FIXED: Atomic check-and-increment
async acquireConnection(): Promise<Connection> {
  return this.mutex.acquire(async () => {
    if (this.activeConnections >= this.maxConnections) {
      throw new PoolExhaustedError();
    }
    this.activeConnections++;
    return this.createConnection();
  });
}

</details>

### Stage 4: Summary
```bash
dilagent manager summary --working-directory ./debug-session

# Install
npm install -g dilagent

# Run the complete workflow in one command
dilagent manager all \
  --context-directory ./my-project \
  --working-directory ./debug-session \
  --hypothesis-count 3 \
  --llm claude

# Key options:
# --llm claude|codex - Choose AI model (Claude recommended)
# --working-directory - Where dilagent stores its files
# --context-directory - The codebase to debug
# --hypothesis-count - Number of hypotheses to generate (default: 3)
# --flaky - Use this flag for intermittent/flaky issues
# --repl - Start interactive mode for complex debugging