Dispatching 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 happen in parallel.
Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
Decision flow: Multiple failures? → Are they independent? (No → single agent) | Independent? → Can work in parallel? (No/shared state → sequential) | Yes → Parallel dispatch
Use when: 3+ test files with different root causes | Multiple subsystems broken independently | Each problem understood without others | No shared state
Don't use when: Failures related (fix one might fix others) | Need full system state | Agents would interfere
The Pattern
-
Identify Independent Domains: Group failures by what's broken (File A: approval flow, File B: batch behavior, File C: abort). Each domain independent.
-
Create Focused Agent Tasks: Each agent gets: specific scope (one file/subsystem), clear goal (make tests pass), constraints (don't change other code), expected output (summary of findings/fixes).
-
Dispatch in Parallel: Task("Fix agent-tool-abort.test.ts")
- Task("Fix batch-completion.test.ts")
- Task("Fix tool-approval-races.test.ts")
- all concurrent.
- Review and Integrate: Read summaries → verify no conflicts → run full test suite → integrate all changes.
Agent Prompt Structure
Good prompts are: Focused (one problem domain), Self-contained (all context included), Specific output (what to return).
Example: "Fix 3 failing tests in agent-tool-abort.test.ts: [list tests + expected behavior]. Timing/race issues. Read tests → identify root cause → fix (event-based waiting, not timeout increases). Return: Summary of findings and fixes."
Common Mistakes
❌ Bad ✅ Good
Too broad: "Fix all tests" Specific: "Fix agent-tool-abort.test.ts"
No context: "Fix race condition" Context: Paste error messages + test names
No constraints: Agent refactors everything Constraints: "Do NOT change production code"
Vague output: "Fix it" Specific: "Return summary of root cause and changes"
When NOT to Use
Related failures (fix one might fix others) | Need full context | Exploratory debugging | Shared state (same files/resources)
Real Example
Scenario: 6 failures across 3 files after refactoring. Decision: Independent domains → parallel dispatch. Results: Agent 1 (timeouts → events), Agent 2 (event structure bug), Agent 3 (async wait). All independent, no conflicts, suite green. 3 problems solved in time of 1.
Key Benefits
Parallelization (simultaneous) | Focus (narrow scope) | Independence (no interference) | Speed (3 → 1 time unit)
Verification
After agents return: Review summaries → check for conflicts → run full suite → spot check for systematic errors.
Blocker Criteria
STOP and report if:
Decision Type Blocker Condition Required Action
Independence check Problems share state or files STOP and use sequential investigation instead
Minimum threshold Fewer than 3 independent failures STOP and investigate directly without parallel dispatch
Conflict detection Agent changes would overlap STOP and re-partition domains
Context requirements Problem requires full system context STOP and use single agent investigation
Cannot Be Overridden
The following requirements CANNOT be waived:
-
Problems MUST be verified independent before parallel dispatch - shared state means sequential
-
Minimum 3 failures REQUIRED for parallel dispatch - fewer means direct investigation
-
Each agent MUST have focused scope (one file/subsystem) - broad scope is FORBIDDEN
-
Agent prompts MUST include constraints about what NOT to change
-
Full test suite MUST run after integrating all agent changes
Severity Calibration
Severity Condition Required Action
CRITICAL Dispatched agents for related/connected failures MUST stop and switch to sequential investigation
CRITICAL Agent changes conflict with each other MUST re-partition domains and re-dispatch
HIGH Agent prompt lacks scope constraints MUST add specific "do NOT change" constraints
HIGH Skipped post-integration test suite MUST run full test suite before completion
MEDIUM Agent prompt lacks expected output format Should add specific output requirements
LOW Could optimize domain partitioning Fix in next iteration
Pressure Resistance
User Says Your Response
"Just dispatch agents for all failures, don't analyze" "MUST verify independence first. Related failures need sequential investigation to avoid conflicts."
"Two failures is enough for parallel dispatch" "CANNOT dispatch for fewer than 3 failures. Direct investigation is faster for 1-2 problems."
"Skip the verification step, agents finished successfully" "MUST run full test suite after integration. Agent success doesn't guarantee no conflicts."
"Give agents broad scope to fix more issues" "Focused scope prevents interference. MUST limit each agent to one file/subsystem."
Anti-Rationalization Table
Rationalization Why It's WRONG Required Action
"These failures look independent enough" Looking independent ≠ verified independent; check for shared state MUST verify independence before dispatch
"Dispatching for 2 failures saves time" Overhead of parallel dispatch exceeds benefit for <3 failures MUST investigate directly if fewer than 3
"Agents can figure out their own scope" Unclear scope causes agents to interfere with each other MUST provide explicit scope and constraints
"Test suite passed for each agent" Individual success doesn't catch integration conflicts MUST run full suite after integration
"Re-partitioning is too much work" Conflicting changes create more work than re-partitioning MUST re-partition if domains overlap