debug-council

# Debug Council: Research-Aligned Self-Consistency

Pure implementation of self-consistency (Wang et al., 2022). Each agent receives the **raw user prompt** and explores/debugs **independently**. No pre-processing, no shared context. Majority voting selects the answer.

**Use this for bugs and problems with ONE correct answer.**

## Step 0: Ask User How Many Agents

Before doing anything else, **ask the user how many solver agents to use**:

```
How many debug agents would you like me to use? (3-10)

Recommendations:
- 3 agents: Faster, still reliable
- 5 agents: Good balance
- 7 agents: High confidence
- 10 agents: Maximum confidence (critical bugs)

Note: Each agent will independently explore the codebase and find the bug.
This takes longer but provides true independence per the research.
```

Wait for the user's response. If they specified a number (e.g., "debug council of 5"), use that.

**Minimum: 3 agents** | **Maximum: 10 agents**

---

## CRITICAL: Pure Research Alignment

### What This Means

1. **NO orchestrator exploration** - Do NOT read files or gather context before spawning agents
2. **Raw user prompt to all agents** - Each agent gets the user's original request, unchanged
3. **Each agent explores independently** - Agents discover the codebase themselves
4. **True independence** - No shared context, no cross-contamination

### Why This Matters

The research shows that **independent samples** converge on correct answers. If we pre-process or share context, we:
- Introduce orchestrator bias
- Reduce independence
- May miss what individual agents would discover

---

## Workflow

### Step 1: Capture the Raw User Prompt

Take the user's request **exactly as stated**. Do NOT:
- ❌ Read files first
- ❌ Explore the codebase
- ❌ Add context
- ❌ Rephrase or enhance the prompt

Just capture what the user said.

### Step 2: Spawn Agents IN PARALLEL with RAW PROMPT

Spawn ALL agents simultaneously. Each gets the **exact same raw prompt**:

```
Task(agent: "debug-solver-1", prompt: "[USER'S EXACT WORDS]")
Task(agent: "debug-solver-2", prompt: "[USER'S EXACT WORDS]")
Task(agent: "debug-solver-3", prompt: "[USER'S EXACT WORDS]")
... (all in the SAME batch - parallel execution)
```

**DO NOT modify the prompt. DO NOT add context. Raw user words only.**

### Step 3: Agents Work Independently

Each agent will:
1. Read and understand the user's request
2. Explore the codebase using their tools (Read, Grep, Glob, LS)
3. Identify the root cause
4. Reason through solutions (chain-of-thought)
5. Generate a complete fix

**Each agent works in complete isolation** - they cannot see what other agents are doing or have found.

### Step 4: Track Progress & Collect Solutions

As agents complete, **show progress to the user**:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     AGENT PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☑ Agent 1 - Complete
☑ Agent 2 - Complete  
☑ Agent 3 - Complete
☐ Agent 4 - Working...
☐ Agent 5 - Working...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Update this display as each agent finishes. When all complete:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                     AGENT PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☑ Agent 1 - Complete ✓
☑ Agent 2 - Complete ✓
☑ Agent 3 - Complete ✓
☑ Agent 4 - Complete ✓
☑ Agent 5 - Complete ✓

All agents finished! Analyzing solutions...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Collect all outputs for voting.

### Step 5: Majority Voting

**Group solutions by their core approach/answer:**

1. Identify the **key decision** in each solution
2. Group solutions that make the same key decision
3. Count how many agents chose each approach

**Voting rules:**
- **Clear majority (≥50%)**: Select that solution, HIGH confidence
- **Plurality (highest < 50%)**: Select that solution, MEDIUM confidence
- **No clear winner**: Analyze disagreement, LOW confidence

### Step 6: Implement the Winner

Implement the majority solution. Do NOT synthesize or merge - use the winning answer as-is.

### Step 7: Report Results

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                    DEBUG COUNCIL RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📊 Voting Summary

| Approach | Description | Agents | Votes |
|----------|-------------|--------|-------|
| ✅ A | [description] | 1, 2, 4, 5, 7 | **5/7** |
| B | [description] | 3, 6 | 2/7 |

**Winner: Approach A** (71% consensus)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🔍 What Each Agent Found

### Agent 1
- Files explored: [list]
- Root cause identified: [summary]
- Solution: [brief]

### Agent 2
- Files explored: [list]
- Root cause identified: [summary]
- Solution: [brief]

... (for each agent)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🧠 Reasoning Highlights

### Why majority chose Approach A:
- Agent 1: "[key insight]"
- Agent 2: "[key insight]"
- Agent 4: "[key insight]"

### Why minority chose differently:
- Agent 3: "[different perspective]"

### Valuable minority insight:
[Any good ideas from minority that might be worth noting]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 📈 Confidence: HIGH/MEDIUM/LOW

[Explanation based on voting distribution and reasoning quality]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## ✅ Selected Solution

[The complete winning solution]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## 🔧 Implementation

[The actual code change being made]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Configuration

| Mode | Agents | Use Case |
|------|--------|----------|
| `debug council of 3` | 3 | Faster, still reliable |
| `debug council of 5` | 5 | Good balance |
| `debug council of 7` | 7 | High confidence |
| `debug council of 10` | 10 | Maximum confidence |

If user just says `debug council`, ask them to choose.

---

## Research Basis

Based on "Self-Consistency Improves Chain of Thought Reasoning in Language Models" (Wang et al., 2022):

| Principle | Our Implementation |
|-----------|-------------------|
| Same prompt to all | Raw user prompt, unmodified |
| Independent samples | Each agent explores independently |
| No shared context | No orchestrator pre-processing |
| Chain-of-thought | Agents use ultrathink |
| Majority voting | Count approaches, select majority |

---

## Why This is Slower (And Why That's OK)

Each agent independently:
- Explores the codebase
- Reads relevant files
- Reasons through the problem
- Generates a solution

This takes **3-10x longer** than shared-context approaches, but provides:
- **True independence** - no orchestrator bias
- **Diverse exploration** - agents may find different things
- **Research alignment** - matches the paper exactly
- **Maximum reliability** - for when accuracy matters most

**Use this for critical problems where getting it right matters more than getting it fast.**

---

## Agents

10 identical debug solver agents in `agents/` directory:
- `debug-solver-1` through `debug-solver-10`

All agents:
- Same instructions
- Same temperature (0.7)
- Same tools (Read, Grep, Glob, LS)
- Use ultrathink (extended thinking)
- Focus on finding the ONE correct answer

Diversity comes from sampling randomness and independent exploration, not different prompts.