| name | dispatching-parallel-agents |
| description | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. Dispatches one focused agent per problem domain, runs them concurrently, then integrates. |
Dispatching Parallel Agents
Core Principle
Dispatch one agent per independent problem domain. Let them work concurrently.
3 problems solved in parallel = time of 1.
When to Use
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
Do NOT use when:
- Failures are related (fixing one might fix others)
- Agents would edit the same files
- You need full system context to understand any single problem
The Pattern
1. Identify Independent Domains
Group problems by what's broken. Each domain must be fixable independently.
2. Create Focused Agent Tasks
Each agent gets:
- Specific scope: One test file or subsystem
- Clear goal: Exactly what to achieve
- Constraints: What NOT to change
- Expected output: Summary of what was found and fixed
3. Dispatch in Parallel
Task("Fix auth-flow.test.ts failures — timing issues in login flow")
Task("Fix payment-webhook.test.ts failures — missing mock for Stripe")
Task("Fix user-profile.test.ts failures — stale closure in useEffect")
4. Review and Integrate
- Read each summary
- Verify fixes don't conflict (check for edits to same files)
- Run full test suite
- Integrate all changes
Agent Prompt Structure
Good prompts are:
- Focused — one clear problem domain
- Self-contained — all context to understand the problem included
- Specific about output — what should the agent return?
Fix the 3 failing tests in src/auth/auth-flow.test.ts:
1. "should redirect after login" - expects /dashboard but gets /
2. "should persist session" - session expires immediately
3. "should handle expired tokens" - throws instead of redirecting
Root context: auth was refactored in commit a1b2c3 to use JWT.
Do NOT change production code — test-only fix unless you find a real auth bug.
Return: what you found and what you changed.
Common Mistakes
- Too broad: "Fix all the tests" → agent gets lost
- No constraints → agent refactors everything
- No expected output → you don't know what changed
- Parallel agents editing the same files → conflicts
Verification After Agents Return
- Review each summary — understand what changed
- Check for conflicts — did agents edit the same code?
- Run full suite — verify all fixes work together
- Spot check — agents can make systematic errors
