dispatching-parallel-agents

Dispatch parallel agents

Overview

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can proceed in parallel.

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

Announce at the start:"I am using the dispatching-parallel-agents skill to dispatch parallel agents to handle independent problem domains."

When to use

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "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 fail with different root causes
• Multiple subsystems are each independently broken
• Each problem can be understood without the context of the other problems
• There is no shared state between investigations

Do not use when:

• Failures are related (fixing one may fix the others)
• You need to understand the full system state
• The agents will interfere with each other

Pattern

1. Identify independent domains

Group failures by what is 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 does not affect the abort tests.

2. Create focused agent tasks

Each agent gets:

• Clear scope: one test file or subsystem
• Clear goal: make these tests pass
• Constraints: do not change other code
• Expected output: a summary of findings and fixes

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 the agents return:

• Read each summary
• Confirm the fixes do not conflict
• Run the full test suite
• Integrate all changes

Agent prompt structure

A good agent prompt has:

1. Focused - one clear problem domain
2. Self-contained - all the context needed to understand the problem
3. Specific 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
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"—the agent gets lost ✅ Specific:"Fix agent-tool-abort.test.ts"—focused scope

❌ No context:"Fix the race condition"—the agent does not know where ✅ With context: paste the error message and test name

❌ No constraints: the agent may overhaul everything ✅ With constraints:"Do not change production code" or "only fix tests"

❌ Vague output:"Fix it"—you do not know what was changed ✅ Specific:"Return a summary of the root cause and changes"

When not to use

Related failures: fixing one may fix the others—investigate them together first Need full context: understanding requires looking at the whole system Exploratory debugging: you do not yet know what is broken Shared state: Agents can interfere with each other (editing the same file, using the same resource)

Real-world case

Scenario: After a large refactor, 6 tests across 3 files failed

Failures:

• agent-tool-abort.test.ts: 3 failures (timing issues)
• batch-completion-behavior.test.ts: 2 failures (tools not executed)
• tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Decision: Independent domains—abort logic, batch completion, and race conditions are each independent

Dispatch:

Agent 1 → 修 agent-tool-abort.test.ts
Agent 2 → 修 batch-completion-behavior.test.ts
Agent 3 → 修 tool-approval-race-conditions.test.ts

Results:

• Agent 1: Replaced timeout with timing wait
• Agent 2: Fixed event structure bug (threadId in wrong position)
• Agent 3: Added a wait before asynchronous tool execution completes

Integration: All fixes are independent, conflict-free, and the full suite passes

Time saved: 3 issues resolved in parallel vs sequentially

Core benefits

1. Parallelization - Multiple investigations proceed simultaneously
2. Focus - Each agent has a narrow scope and less context to track
3. Independence - Agents do not interfere with each other
4. Speed - 3 issues resolved in the time of 1

Verification

After agents return:

1. Review each summary - Understand what changed
2. Check for conflicts - Did the agents modify the same code?
3. Run the full suite - Confirm all fixes work together
4. Spot-check - Agents may make systematic errors