Skip to main content
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:
Replaced timeouts with event-based waiting
  • Changed setTimeout(100) to waitForEvent('tool-aborted')
  • Fixed race condition in abort handler
  • All 3 tests now pass
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us