> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Multiple failures?">
    Do you have 2+ failing test files, broken subsystems, or bugs?
  </Step>

  <Step title="Are they independent?">
    Can each problem be understood without context from the others?

    * **Yes** → Continue to next step
    * **No (related)** → Single agent investigates all
  </Step>

  <Step title="Can they work in parallel?">
    Do they share state that would cause interference?

    * **Yes (no shared state)** → Parallel dispatch
    * **No (shared state)** → Sequential agents
  </Step>
</Steps>

### Use When

<Tip>
  * 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
</Tip>

### Don't Use When

<Warning>
  * 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)
</Warning>

## 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

```typescript theme={null}
// 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

```markdown theme={null}
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

<CardGroup cols={2}>
  <Card title="Too Broad" icon="xmark">
    ❌ "Fix all the tests" - agent gets lost

    ✅ "Fix agent-tool-abort.test.ts" - focused scope
  </Card>

  <Card title="No Context" icon="xmark">
    ❌ "Fix the race condition" - agent doesn't know where

    ✅ Paste the error messages and test names
  </Card>

  <Card title="No Constraints" icon="xmark">
    ❌ Agent might refactor everything

    ✅ "Do NOT change production code" or "Fix tests only"
  </Card>

  <Card title="Vague Output" icon="xmark">
    ❌ "Fix it" - you don't know what changed

    ✅ "Return summary of root cause and changes"
  </Card>
</CardGroup>

## 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:**

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

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

**Time saved:** 3 problems solved in parallel vs sequentially

## Key Benefits

<CardGroup cols={2}>
  <Card title="Parallelization" icon="bolt">
    Multiple investigations happen simultaneously
  </Card>

  <Card title="Focus" icon="bullseye">
    Each agent has narrow scope, less context to track
  </Card>

  <Card title="Independence" icon="shield">
    Agents don't interfere with each other
  </Card>

  <Card title="Speed" icon="gauge-high">
    3 problems solved in time of 1
  </Card>
</CardGroup>

## Verification After Agents Return

<Steps>
  <Step title="Review each summary">
    Understand what changed in each domain
  </Step>

  <Step title="Check for conflicts">
    Did agents edit the same code or make conflicting assumptions?
  </Step>

  <Step title="Run full suite">
    Verify all fixes work together:

    ```bash theme={null}
    npm test
    cargo test
    pytest
    ```
  </Step>

  <Step title="Spot check">
    Agents can make systematic errors. Verify the logic makes sense.
  </Step>
</Steps>

## 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](/skills/verification-before-completion) - Verify agent work before trusting results
* [Requesting Code Review](/skills/requesting-code-review) - Review integrated changes after parallel work