dispatching-parallel-agents

$2b

"Multiple failures?" -> "Are they independent?" [label="yes"];

"Are they independent?" -> "Single agent investigates all" [label="no - related"];

"Are they independent?" -> "Can they work in parallel?" [label="yes"];

"Can they work in parallel?" -> "Parallel dispatch" [label="yes"];

"Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];

}

**Use when:**

- 3+ test files failing with different root causes

- Multiple subsystems broken independently

- Each problem can be understood without context from others

- No shared state between investigations

**Don't use when:**

- Failures are related (fix one might fix others)

- Need to understand full system state

- Agents would interfere with each other

## The Pattern

### 1. Identify Independent Domains

Group failures by what's broken:

- File A tests: Tool approval flow

- File B tests: Batch completion behavior

- File C tests: Abort functionality

Each domain is independent - fixing tool approval doesn't affect abort tests.

### 2. Create Focused Agent Tasks

Each agent gets:

- **Specific scope:** One test file or subsystem

- **Clear goal:** Make these tests pass

- **Constraints:** Don't change other code

- **Expected output:** Summary of what you found and fixed

### 3. Dispatch in Parallel

// In Claude Code / AI environment

Task("Fix agent-tool-abort.test.ts failures")

Task("Fix batch-completion-behavior.test.ts failures")

Task("Fix tool-approval-race-conditions.test.ts failures")

// All three run concurrently

### 4. Review and Integrate

When agents return:

- Read each summary

- Verify fixes don't conflict

- Run full test suite

- Integrate all changes

## Agent Prompt Structure

Good agent prompts are:

- **Focused** - One clear problem domain

- **Self-contained** - All context needed to understand the problem

- **Specific about output** - What should the agent return?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message

1. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed

1. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies

1. Identify root cause - timing issues or actual bugs?

1. Fix by:

- Replacing arbitrary timeouts with event-based waiting

- Fixing bugs in abort implementation if found

- Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

## Common Mistakes

**❌ Too broad:** "Fix all the tests" - agent gets lost
**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope

**❌ No context:** "Fix the race condition" - agent doesn't know where
**✅ Context:** Paste the error messages and test names

**❌ No constraints:** Agent might refactor everything
**✅ Constraints:** "Do NOT change production code" or "Fix tests only"

**❌ Vague output:** "Fix it" - you don't know what changed
**✅ Specific:** "Return summary of root cause and changes"

## When NOT to Use

**Related failures:** Fixing one might fix others - investigate together first
**Need full context:** Understanding requires seeing entire system
**Exploratory debugging:** You don't know what's broken yet
**Shared state:** Agents would interfere (editing same files, using same resources)

## Real Example from Session

**Scenario:** 6 test failures across 3 files after major refactoring

**Failures:**

- agent-tool-abort.test.ts: 3 failures (timing issues)

- batch-completion-behavior.test.ts: 2 failures (tools not executing)

- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions

**Dispatch:**

Agent 1 → Fix agent-tool-abort.test.ts

Agent 2 → Fix batch-completion-behavior.test.ts

Agent 3 → Fix tool-approval-race-conditions.test.ts