Dispatching Parallel Agents

Execute independent tasks concurrently using specialized agents for faster problem resolution

When facing multiple independent problems, investigating them sequentially wastes time. Dispatch one agent per independent problem domain and let them work concurrently.

Core Principle

Dispatch one agent per independent problem domain. Let them work concurrently.

Parallel investigation of independent failures is orders of magnitude faster than sequential debugging.

When to Use

1. Multiple failures?

   Do you have 2+ failing test files, broken subsystems, or bugs?

2. Are they independent?

   Can each problem be understood without context from the others?

   • Yes → Continue to next step
   • No (related) → Single agent investigates all
3. Can they work in parallel?

   Do they share state that would cause interference?

   • Yes (no shared state) → Parallel dispatch
   • No (shared state) → Sequential agents

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 (fixing one might fix others)
• Need to understand full system state
• Agents would interfere with each other
• Exploratory debugging (you don’t know what’s broken yet)

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:

1. Read each summary
2. Verify fixes don’t conflict
3. Run full test suite
4. Integrate all changes

Agent Prompt Structure

Good agent prompts are:

1. Focused - One clear problem domain
2. Self-contained - All context needed to understand the problem
3. Specific about output - What should the agent return?

Example Prompt

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
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "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
2. Identify root cause - timing issues or actual bugs?
3. 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

✅ “Fix agent-tool-abort.test.ts” - focused scope

No Context

❌ “Fix the race condition” - agent doesn’t know where

✅ Paste the error messages and test names

No Constraints

❌ Agent might refactor everything

✅ “Do NOT change production code” or “Fix tests only”

Vague Output

❌ “Fix it” - you don’t know what changed

✅ “Return summary of root cause and changes”

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

Results:

Agent 1 Results

Replaced timeouts with event-based waiting

• Changed setTimeout(100) to waitForEvent('tool-aborted')
• Fixed race condition in abort handler
• All 3 tests now pass

Agent 2 Results

Fixed event structure bug (threadId in wrong place)

• Moved threadId from nested object to top level
• Updated event handler to read correct location
• Both tests now pass

Agent 3 Results

Added wait for async tool execution to complete

• Test was checking results before tools executed
• Added await waitForCompletion() before assertions
• Test now passes

Integration: All fixes independent, no conflicts, full suite green

Time saved: 3 problems solved in parallel vs sequentially

Key Benefits

Parallelization

Multiple investigations happen simultaneously

Focus

Each agent has narrow scope, less context to track

Independence

Agents don’t interfere with each other

Speed

3 problems solved in time of 1

Verification After Agents Return

1. Review each summary

   Understand what changed in each domain

2. Check for conflicts

   Did agents edit the same code or make conflicting assumptions?

3. Run full suite

   Verify all fixes work together:

   npm test
   cargo test
   pytest
   
4. Spot check

   Agents can make systematic errors. Verify the logic makes sense.

Decision Tree

Multiple independent failures?
├─ Related failures → Single agent investigates
└─ Independent failures
    ├─ Shared state → Sequential agents
    └─ No shared state → Parallel dispatch ✓
        ├─ Create focused prompts
        ├─ Dispatch all agents
        ├─ Review summaries
        ├─ Check for conflicts
        └─ Integrate changes

Performance Impact

From real debugging session (2025-10-03):

6 failures across 3 files
→ 3 agents dispatched in parallel
→ All investigations completed concurrently
→ All fixes integrated successfully
→ Zero conflicts between agent changes
→ Time: ~1x instead of ~3x

Related Skills

• Verification Before Completion - Verify agent work before trusting results
• Requesting Code Review - Review integrated changes after parallel work