Dispatching Parallel Agents

Dispatching Parallel Agents

Overview

When multiple unrelated failures occur (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 This Skill

Activate this skill when facing:

• 3+ test files failing with different root causes
• Multiple subsystems broken independently
• Each problem is self-contained - can be understood without context from others
• No shared state between investigations
• Clear domain boundaries - fixing one won't affect others

Don't use when:

• Failures are related (fix one might fix others)
• Need to understand full system state first
• Agents would interfere with each other (editing same files)
• Exploratory debugging (don't know what's broken yet)

The Iron Law

One agent, one problem domain, one clear outcome.
Never overlap scopes. Never share state. Always integrate consciously.

Core Principles

Independence is Key

Problems must be truly independent - no shared files, no related root causes, no dependencies between fixes.

Focus Over Breadth

Each agent gets narrow scope: one test file, one subsystem, one clear goal. Broad tasks lead to confusion.

Clear Output Required

Every agent must return a summary: what was found, what was fixed, what changed. No silent fixes.

Conscious Integration

Don't blindly merge agent work. Review summaries, check conflicts, run full suite, verify compatibility.

Quick Start

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

→ agent-prompts.md for prompt templates and examples

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

→ coordination-patterns.md for dispatch strategies

4. Review and Integrate

When agents return:

• Read each summary - understand what changed
• Verify fixes don't conflict - check for same file edits
• Run full test suite - ensure compatibility
• Spot check changes - agents can make systematic errors

→ troubleshooting.md for conflict resolution

Decision Tree

Multiple failures?
  └→ Are they independent?
      ├→ NO (related) → Single agent investigates all
      └→ YES → Can they work in parallel?
          ├→ NO (shared state) → Sequential agents
          └→ YES → Parallel dispatch ✓

Key Benefits

1. Parallelization - Multiple investigations happen simultaneously 2. Focus - Each agent has narrow scope, less context to track 3. Independence - Agents don't interfere with each other 4. Speed - N problems solved in time of 1

Navigation

Pattern Reference

• [Coordination Patterns](references/coordination-patterns.md) - Dispatch strategies, domain identification, integration workflows

Agent Management

• [Agent Prompts](references/agent-prompts.md) - Prompt structure, templates, common mistakes, constraints

Learning Resources

• [Examples](references/examples.md) - Real-world scenarios, case studies, time savings analysis

Problem Solving

• [Troubleshooting](references/troubleshooting.md) - Conflict resolution, verification strategies, common pitfalls

Related Skills

When dispatching parallel agents, consider these complementary skills (available in the skill library):

• pm-workflow: PM coordination and task management - manage multiple agent workstreams effectively
• test-driven-development: TDD patterns that benefit from parallel fixing - understand test failures before parallelizing
• verification-before-completion: Integration verification - ensure parallel agent work integrates correctly

Key Reminders

1. Independence is mandatory - Related failures need single-agent investigation 2. Focus beats breadth - Narrow scope per agent prevents confusion 3. Always verify integration - Don't blindly merge agent work 4. Clear outputs required - Every agent returns summary of changes 5. Parallelization has overhead - Only worth it for 3+ independent problems

Red Flags - STOP

STOP immediately if:

• Agents are editing the same files (scope overlap)
• Fixes from one agent break another's work (hidden dependencies)
• Problem domains cannot be clearly separated (not independent)
• Agents return no summary (can't verify changes)
• Integration requires major refactoring (conflicts)

When in doubt: Start with one agent, understand the landscape, then dispatch if truly independent.

Integration with Other Skills

Prerequisite: Basic understanding of problem domains and test structure Complementary: PM-Workflow skill for coordinating multiple agents (see skill library) Domain-specific: Testing skills for understanding test failures (available in skill library)

Real-World Impact

From debugging session (2025-10-03):

• 6 failures across 3 test files
• 3 agents dispatched in parallel
• All investigations completed concurrently
• Zero conflicts between agent changes
• Time saved: 3 problems solved in parallel vs sequentially

→ examples.md for detailed case study

Agent Prompts

Complete guide to writing effective prompts for parallel agent dispatch.

Prompt Structure

The Four Essential Elements

Every agent prompt must include:

1. Scope - What domain/files the agent works on 2. Goal - What success looks like 3. Constraints - What the agent should NOT do 4. Output - What to return when complete

Missing any element leads to:

• Scope missing → Agent changes too much
• Goal missing → Agent doesn't know when done
• Constraints missing → Agent breaks other things
• Output missing → You can't verify what changed

Template: Test File Fixing

Fix the [N] failing tests in [file path]:

[List each failing test name and error message]

Context:
[Why these tests are failing - recent changes, library updates, etc.]

Your task:
1. Read the test file and understand what each test verifies
2. Identify root cause - is it the test or the implementation?
3. Fix by:
   [Specific guidance based on failure type]

Constraints:
- Only modify [allowed files]
- Do NOT change [protected files/APIs]
- [Other specific constraints]

Return:
- Summary of root cause
- List of files changed with brief explanation
- Confirmation all tests in scope now pass

Template: Subsystem Investigation

Investigate and fix issues in [subsystem name]:

Symptoms:
[List observed failures, errors, unexpected behavior]

Your scope:
[List files/modules in this subsystem]

Your task:
1. Reproduce the issue locally
2. Identify root cause through debugging
3. Implement minimal fix
4. Verify fix resolves symptoms

Constraints:
- Stay within [subsystem] boundaries
- Coordinate with me before changing shared utilities
- Don't modify external dependencies

Return:
- Root cause explanation
- Your fix approach and rationale
- List of changed files
- Verification steps you performed

Template: Feature Bug Fix

Fix bug in [feature name]:

Bug report:
[User-reported issue or test failure]

Expected behavior:
[What should happen]

Actual behavior:
[What currently happens]

Your task:
1. Locate where this behavior is implemented
2. Identify why actual ≠ expected
3. Fix the implementation or test expectations
4. Add test coverage if missing

Constraints:
- Maintain backward compatibility for [API/interface]
- Don't change [other features]
- Keep fix minimal and focused

Return:
- Root cause (why did this bug exist?)
- Your fix and why it's correct
- Test coverage added/modified

Good vs Bad Prompts

Example 1: Test Failures

❌ Bad:

Fix the tests that are failing.

Problems:

• No scope (which tests?)
• No context (why failing?)
• No constraints (can change anything)
• No output format

✅ Good:

Fix the 3 failing tests in src/auth/login.test.ts:

1. "should handle expired sessions" - TypeError: Cannot read property 'refresh' of undefined
2. "should refresh tokens" - Expected token to be defined, got undefined
3. "should logout on invalid token" - Expected logout() to be called

Context: These started failing after auth library upgrade v2→v3

Your task:
1. Review auth library v3 migration guide
2. Update TokenService usage to v3 API
3. Verify all 3 tests pass

Constraints:
- Only modify login.service.ts and login.test.ts
- Don't change TokenService (external library)

Return:
- What changed in v3 API
- Your implementation changes
- Test status after fix

Example 2: Subsystem Issues

❌ Bad:

The payment stuff is broken, please fix.

Problems:

• "Payment stuff" too vague
• "Broken" undefined (what's the symptom?)
• No specific task

✅ Good:

Fix payment processing errors in checkout flow:

Errors observed:
- Stripe webhook receiving 500 responses
- Payment confirmations not saving to database
- Users not receiving email receipts

Your scope:
- src/payments/stripe-webhook.controller.ts
- src/payments/payment.service.ts
- src/payments/payment.model.ts

Your task:
1. Reproduce webhook failure with test events
2. Identify why confirmations aren't saving
3. Fix the payment processing pipeline
4. Verify webhooks return 200 and emails send

Constraints:
- Don't modify Stripe SDK usage (library is correct)
- Don't change payment.model.ts schema (requires migration)
- Keep email service calls async (don't block webhook)

Return:
- Root cause of each error
- Your fixes and verification

Example 3: Investigation + Fix

❌ Bad:

Look into the performance problems.

Problems:

• What performance problems where?
• What's the success criteria?
• Should agent fix or just report?

✅ Good:

Investigate and fix slow response times in product search API:

Observed: /api/products/search takes 3-5 seconds (should be <500ms)

Your scope:
- src/products/search.service.ts
- src/products/search.controller.ts
- Database queries for product search

Your task:
1. Profile the search endpoint to identify bottleneck
2. Analyze database query performance
3. Optimize slow queries or add caching
4. Verify response time <500ms for typical searches

Constraints:
- Don't change API contract (request/response shape)
- Keep search results accurate (no false positives)
- If caching, implement proper invalidation

Return:
- Profiling results (what was slow)
- Your optimization approach
- Performance before/after measurements

Context Provision

What Context to Include

Always include:

• Exact error messages (copy-paste)
• Test names that are failing
• Recent changes that might be related
• Expected vs actual behavior

Include when relevant:

• Library/framework versions
• Environment differences (prod vs dev)
• User reports or bug tickets
• Related issues that were fixed

Don't include:

• Entire codebase (agent will search)
• Unrelated files
• Historical context beyond 1-2 changes back
• Speculation ("I think maybe...")

Example: Rich Context

Fix 3 failures in batch-completion-behavior.test.ts:

Test failures:
1. "should execute all tools in batch"
   Error: Expected 3 tool executions, received 0

2. "should complete batch when all tools finish"
   Error: Batch status is 'pending', expected 'completed'

3. "should handle partial batch completion"
   Error: completedCount is 0, expected 2

Context:
- Started failing after refactoring event emission (commit abc123)
- Changed from direct method calls to event-based architecture
- Other tests pass, only batch execution affected

Relevant code:
- src/batch/batch-executor.ts (execution logic)
- src/batch/batch.service.ts (status tracking)
- Tests use mock tools that resolve after 100ms

Your task:
1. Review how events are emitted in new architecture
2. Check if batch executor is listening to correct events
3. Verify event payload structure matches expectations
4. Fix event wiring or update tests if behavior changed intentionally

Constraints:
- Keep event-based architecture (don't revert to direct calls)
- Don't modify mock tools in tests
- Ensure fix works for both sync and async tools

Return:
- What was wrong with event wiring
- Your fix
- Verification all 3 tests pass

Common Mistakes

Mistake 1: Too Broad

❌ Bad:

Fix all the auth issues and make sure everything works.

Why bad:

• "All auth issues" could be 50 files
• "Everything works" has no definition
• Agent doesn't know where to start

✅ Fix:

Fix the 2 failing tests in auth/session.test.ts:
- Test 1: [specific test name and error]
- Test 2: [specific test name and error]

Success = both tests pass

Mistake 2: No Context

❌ Bad:

Fix the race condition in agent-tool-abort.test.ts

Why bad:

• Which race condition?
• What's the symptom?
• What was changed recently?

✅ Fix:

Fix race condition in agent-tool-abort.test.ts:

Symptom: Test "should abort tool with partial output" is flaky
- Passes 70% of time, fails 30%
- When fails: expects 'interrupted at' in message, message is empty

Likely cause: Test doesn't wait for abort to complete before asserting

Your task: Replace arbitrary timeout with event-based waiting

Mistake 3: Unclear Constraints

❌ Bad:

Fix the tests but don't break anything.

Why bad:

• "Don't break anything" is obvious but not actionable
• Doesn't specify what agent CAN change

✅ Fix:

Fix the tests in login.test.ts.

Allowed changes:
- login.service.ts (implementation)
- login.test.ts (test expectations)

NOT allowed:
- auth.controller.ts (API contract)
- user.model.ts (database schema)
- Shared utilities in /common

Coordinate with me before changing anything else.

Mistake 4: No Output Specification

❌ Bad:

Fix the payment processing bugs.

Why bad:

• Agent might fix and not tell you what changed
• You can't verify the fix without reading all the code

✅ Fix:

Fix payment processing bugs.

When complete, return:
1. Root cause analysis - why were payments failing?
2. List of files you changed with brief explanation each
3. How you verified the fix (tests? manual testing?)
4. Any risks or edge cases to watch for

Advanced Patterns

Pattern: Investigate Then Fix

Use when: Root cause unknown, agent needs to explore

Investigate why user profile updates are failing:

Symptoms:
- PUT /api/users/:id returns 200 but changes don't persist
- Database shows old values after update
- No errors in logs

Your approach:
1. **Investigate** (15-20 min):
   - Add debug logging to update flow
   - Check if database transaction commits
   - Verify request payload reaches database layer

2. **Report findings** to me:
   - What you discovered
   - Proposed fix approach

3. **Wait for confirmation** before implementing fix

4. **Implement** approved fix

This two-phase approach ensures we fix root cause, not symptoms.

Pattern: Parallel Agents with Shared Learning

Use when: Multiple agents might discover related info

[Agent 1 - Auth subsystem]
Fix auth issues, report any shared utility bugs you find.

[Agent 2 - Payment subsystem]
Fix payment issues, report any shared utility bugs you find.

[Agent 3 - Notification subsystem]
Fix notification issues, report any shared utility bugs you find.

If any agent finds a shared utility bug:
1. Report it immediately
2. Pause your other work
3. Wait for coordinator to decide if one agent should fix centrally

Pattern: Staged Dispatch

Use when: Some problems must be fixed before others

[Agent 1 - Priority 1]
Fix database connection pool exhaustion.
This is blocking other work - highest priority.

Return ASAP: Is it fixed?

[Agent 2 & 3 - Will dispatch after Agent 1]
Waiting for database fix before investigating:
- Agent 2: Session timeout issues (might be due to DB)
- Agent 3: Query performance (definitely due to DB)

Prompt Checklist

Before dispatching any agent:

□ Scope clearly defined (files, boundaries)
□ Goal is specific and measurable
□ Context includes error messages and recent changes
□ Constraints specify what NOT to change
□ Output format specified (summary, file list, verification)
□ Agent knows when to ask for help vs decide independently
□ Integration plan considered (how will this merge with other agent work?)

Template Library

Quick Template: Single Test File

Fix [N] failing tests in [file]:

Tests:
1. [test name] - [error]
2. [test name] - [error]

Task: [what to do]
Don't: [what not to change]
Return: Root cause + changes + verification

Quick Template: Bug Investigation

Investigate [symptom]:

Context: [when it happens, what changed]
Scope: [files to look at]
Task: Find root cause, propose fix, wait for approval
Return: Analysis + proposed solution + risks

Quick Template: Performance Issue

Optimize [slow operation]:

Current: [performance measurement]
Target: [performance goal]
Scope: [what to optimize]
Constraints: [what must stay the same]
Return: Bottleneck analysis + optimization + before/after

Real-World Examples

Example: Actual Parallel Dispatch

From debugging session (2025-10-03):

Agent 1 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.

Agent 2 Prompt:

Fix the 2 failing tests in src/agents/batch-completion-behavior.test.ts:

1. "should execute all tools in batch" - expected 3 tool executions, received 0
2. "should complete batch when all tools finish" - batch status is 'pending', expected 'completed'

Context: These started failing after event refactoring.

Your task:
1. Verify event emission in batch executor
2. Check event listeners are set up correctly
3. Fix event wiring or update test expectations

Return: Summary of what you found and what you fixed.

Agent 3 Prompt:

Fix the 1 failing test in src/agents/tool-approval-race-conditions.test.ts:

1. "should handle rapid tool approvals" - execution count is 0, expected 3

Likely cause: Test doesn't wait for async execution to complete.

Your task:
1. Add proper waiting for tool execution completion
2. Verify race conditions are actually handled (not just test timing)

Return: Summary of what you found and what you fixed.

Results:

• All agents returned clear summaries
• No scope overlap, no conflicts
• All fixes integrated cleanly
• Full test suite passed

Coordination Patterns

Complete guide to identifying independent domains, dispatching agents, and integrating their work.

Domain Identification Patterns

The Independence Test

Before dispatching parallel agents, verify true independence:

✓ Independent domains:
  - Different test files with unrelated functionality
  - Different subsystems (auth, payments, notifications)
  - Different bug reports from different users
  - Different data processing pipelines

✗ Not independent:
  - Tests failing due to shared database state
  - Cascading failures (one root cause, many symptoms)
  - Features that share core business logic
  - Components with tight coupling

Domain Grouping Strategy

By Test File:

File A: tool-approval-flow.test.ts
File B: batch-completion.test.ts
File C: abort-handling.test.ts
→ 3 domains, each gets one agent

By Subsystem:

Subsystem A: Authentication module
Subsystem B: Payment processing
Subsystem C: Email notifications
→ 3 domains, clear boundaries

By Feature:

Feature A: User registration flow
Feature B: Product search
Feature C: Shopping cart
→ 3 domains, minimal overlap

Anti-Pattern: False Independence

❌ BAD: Treat as independent when they're not
Problem 1: Login tests failing
Problem 2: Dashboard tests failing (needs login)
Problem 3: User profile tests failing (needs login)

→ NOT independent! Root cause is login.
→ Solution: Single agent investigates login first

Dispatch Strategies

Strategy 1: Parallel Task Creation

Best for: Clear, well-defined problems with no discovery needed

// All tasks created at once
Task("Fix authentication flow - login.test.ts 3 failures")
Task("Fix payment processing - checkout.test.ts 2 failures")
Task("Fix email service - notifications.test.ts 4 failures")

// Agents work simultaneously
// You review results when all complete

Advantages:

• Maximum parallelization
• Fastest total time
• Clear workload distribution

Disadvantages:

• Requires upfront domain analysis
• Risk of conflicts if domains overlap
• Hard to adjust if one agent finds systemic issue

Strategy 2: Sequential with Parallel Bursts

Best for: Mixed certainty - some problems clear, others need investigation

// Phase 1: Investigate unclear areas
Task("Investigate root cause of database connection errors")

// Wait for result...

// Phase 2: Based on findings, dispatch parallel fixes
Task("Fix connection pool exhaustion in auth service")
Task("Fix timeout handling in payment service")
Task("Fix retry logic in notification service")

Advantages:

• Reduces risk of false independence
• Adapts to discoveries
• Maintains parallelization where safe

Disadvantages:

• Slower than pure parallel
• Requires decision point between phases

Strategy 3: Hierarchical Dispatch

Best for: Large-scale problems with clear subsystem boundaries

// Level 1: Subsystem leads
Task("Auth subsystem: Investigate and delegate 5 test failures")
Task("Payments subsystem: Investigate and delegate 4 test failures")

// Level 2: Each subsystem agent dispatches focused tasks
// Auth agent creates:
  Task("Fix OAuth token refresh logic")
  Task("Fix session timeout handling")

// Payments agent creates:
  Task("Fix Stripe webhook handling")
  Task("Fix refund processing")

Advantages:

• Scales to large problem sets
• Domain experts coordinate sub-tasks
• Natural verification points

Disadvantages:

• Higher coordination overhead
• More complex integration
• Requires clear subsystem boundaries

Integration Workflows

Integration Pattern 1: Summary Review

When agents return:

1. Read all summaries first

• Don't look at code yet
• Understand what each agent did
• Identify potential conflicts

2. Check for overlaps

• Did multiple agents edit same files?
• Did one agent's fix depend on another's?
• Are there conflicting approaches?

3. Verify independently

• Run each agent's tests in isolation
• Confirm each fix works alone
• Check no new failures introduced

4. Integrate progressively

• Merge one agent's work at a time
• Run full suite after each merge
• Isolate which merge causes conflicts

Integration Pattern 2: Conflict Resolution

When conflicts arise:

Agent A changed: auth.service.ts (lines 50-60)
Agent B changed: auth.service.ts (lines 55-65)
→ Overlap detected!

Resolution steps:
1. Understand both changes - why did each agent change this?
2. Check if both changes needed - or is one redundant?
3. Determine merge strategy:
   a) One change supersedes other
   b) Both changes needed, manual merge
   c) Neither optimal, new solution needed
4. Verify merged version passes both agents' tests

Integration Pattern 3: Full Suite Verification

After integration:

# Run complete test suite
npm test

# Check for unexpected failures
# - Tests that weren't part of any agent's scope
# - Integration points between fixed domains
# - System-level behavior

# If new failures:
# 1. Identify which agent's changes caused it
# 2. Understand why (missing integration consideration?)
# 3. Fix with minimal change
# 4. Re-verify

Scope Management

Clear Scope Definition

Good scope definition:

Agent scope: Fix all failures in src/auth/login.test.ts

Allowed to change:
- src/auth/login.service.ts
- src/auth/login.controller.ts
- Test file itself (if testing wrong behavior)

NOT allowed to change:
- Other auth modules
- Shared utilities (without consultation)
- Database schema
- API contracts (breaking changes)

Expected output:
- Summary of root cause
- List of files changed
- Explanation of fix approach
- Confirmation all 3 tests now pass

Bad scope definition:

❌ "Fix the auth issues"
   → Too vague, agent doesn't know where to focus

❌ "Make all tests pass"
   → Too broad, agent will change anything

❌ "Fix login.test.ts but use your judgment"
   → Unclear constraints, unpredictable changes

Scope Boundaries

Enforce clear boundaries:

Agent A domain: Authentication flow
├── login.service.ts
├── logout.service.ts
├── session.manager.ts
└── auth.test.ts

Agent B domain: User profile
├── profile.service.ts
├── profile.controller.ts
└── profile.test.ts

Shared boundary (coordination needed):
└── user.model.ts (both agents might need to modify)
    → Solution: Neither agent changes it without asking
    → Or: Designate one agent as owner

Communication Patterns

Agent-to-Coordinator Communication

What agents should report:

# Agent Return Template

## Domain
Which test file / subsystem I worked on

## Root Cause
What was actually broken (not symptoms)

## Changes Made
- File A: Modified lines 50-60 to fix X
- File B: Added validation for Y
- Test file: Adjusted expectations for Z

## Verification
All 3 tests in my scope now pass:
✓ Test 1: login with valid credentials
✓ Test 2: login with invalid credentials
✓ Test 3: login with expired session

## Dependencies Discovered
None - my changes are isolated

## Risks
Watch for: Session timeout edge cases in other tests

Coordinator-to-Agent Communication

Clear task assignment:

# Task for Agent

## Your Scope
Fix 3 failures in src/auth/login.test.ts:
1. "should handle expired sessions" - throws TypeError
2. "should refresh tokens" - token undefined
3. "should logout on invalid token" - logout not called

## Context
These started failing after we upgraded auth library v2→v3
Library changed: TokenService API now async

## Constraints
- Fix the implementation or tests (your judgment)
- Don't change other auth files unless necessary
- Don't modify TokenService (external library)

## Expected Output
- Root cause explanation
- List of changes
- Confirmation tests pass

Performance Optimization

Minimizing Coordination Overhead

Trade-off analysis:

1 problem:  Sequential (no parallelization benefit)
2 problems: Marginal benefit (coordination overhead ≈ parallelization gain)
3 problems: Clear benefit (coordination < parallelization gain)
5+ problems: High benefit (scales well)

Exception: Very quick fixes (<5 min each)
→ Sequential might be faster due to low task-switching cost

Optimal Agent Count

Problems: 3-5   → Agents: 3-5 (1:1 mapping)
Problems: 6-10  → Agents: 4-6 (group related problems)
Problems: 10+   → Agents: 5-8 (hierarchical dispatch)

Maximum: ~8 agents (human coordination limit)
→ Beyond 8: Use hierarchical pattern

Advanced Patterns

Pattern: Dependency-Aware Dispatch

When problems have loose dependencies:

Problem A: Must fix first (others depend on it)
Problems B, C, D: Independent once A is fixed

Dispatch strategy:
1. Agent 1 fixes A
2. After A complete, dispatch B, C, D in parallel
3. Integrate all together

Pattern: Speculative Parallel

When independence is likely but uncertain:

Dispatch all agents in parallel BUT:
- Each agent starts with investigation phase
- Agents report if they find shared dependencies
- Coordinator halts others if one finds systemic issue

Example:
3 agents start investigating 3 test files
Agent 1 discovers: "All failures due to config loading bug"
→ Coordinator halts Agent 2 & 3
→ Agent 1 fixes config bug
→ All tests pass

Pattern: Progressive Integration

For large-scale parallel work:

8 agents working on different subsystems

Integration phases:
1. Integrate auth agents (A1, A2) → Verify auth suite
2. Integrate payment agents (P1, P2) → Verify payment suite
3. Integrate all auth + payments → Verify integration
4. Continue with notifications, etc.

Benefit: Catch conflicts early, smaller integration surface

Common Mistakes

Mistake 1: Premature Parallelization

❌ 5 test failures, immediately dispatch 5 agents
✓ Read all 5 failures, identify if root cause is shared
  → Shared: 1 agent fixes root cause
  → Independent: Dispatch in parallel

Mistake 2: Ignoring Soft Dependencies

❌ "Files are separate, must be independent"
✓ Check runtime dependencies:
  - Shared database state
  - Service initialization order
  - Global configuration
  - Shared caches/singletons

Mistake 3: No Integration Plan

❌ Dispatch agents, merge all changes at once, run tests
✓ Plan integration:
  - Which order to merge?
  - How to verify each step?
  - What to do if conflicts arise?

Mistake 4: Vague Boundaries

❌ "Fix auth stuff" + "Fix user stuff"
   → Overlap potential: What is "auth" vs "user"?

✓ "Fix login.test.ts" + "Fix profile.test.ts"
   → Clear file-based boundary

Verification Checklist

Before dispatching:

• [ ] Verified problems are truly independent
• [ ] Defined clear scope for each agent
• [ ] Identified shared boundaries / risks
• [ ] Planned integration approach
• [ ] Estimated if parallelization worth overhead

During execution:

• [ ] Monitoring for agents reporting dependencies
• [ ] Ready to halt if systemic issue found
• [ ] Tracking which agent is working on what

After completion:

• [ ] Read all summaries before integrating
• [ ] Checked for file/scope overlaps
• [ ] Verified each fix in isolation
• [ ] Progressive integration with verification
• [ ] Full suite pass with all changes

Examples

Real-world scenarios, case studies, and time savings analysis from parallel agent dispatch.

Case Study 1: Test Suite Recovery

Scenario: Major refactoring broke 6 tests across 3 files

Initial State

❌ agent-tool-abort.test.ts - 3 failures
   - "should abort tool with partial output capture"
   - "should handle mixed completed and aborted tools"
   - "should properly track pendingToolCount"

❌ batch-completion-behavior.test.ts - 2 failures
   - "should execute all tools in batch"
   - "should complete batch when all tools finish"

❌ tool-approval-race-conditions.test.ts - 1 failure
   - "should handle rapid tool approvals"

Decision Process

Question 1: Are these failures related?

• Abort logic is independent of batch completion
• Batch completion is independent of approval flow
• Each test file tests different subsystem
• Answer: Independent failures ✓

Question 2: Can they be fixed in parallel?

• No shared files being modified
• Each domain has clear boundaries
• Fixes won't interfere with each other
• Answer: Yes, parallel dispatch appropriate ✓

Question 3: Is overhead worth it?

• 3 problem domains, would take ~20 min each sequentially = 60 min
• Parallel: ~20 min total + 5 min integration = 25 min
• Answer: Yes, saves 35 minutes ✓

Execution

Agent 1 Task:

Fix agent-tool-abort.test.ts failures (3 tests)
Focus: Timing/race conditions in abort implementation

Agent 2 Task:

Fix batch-completion-behavior.test.ts failures (2 tests)
Focus: Event emission after architecture refactoring

Agent 3 Task:

Fix tool-approval-race-conditions.test.ts failure (1 test)
Focus: Async execution waiting

Results

Agent 1 Findings:

• Root cause: Tests used arbitrary timeouts (100ms, 200ms)
• Real issue: Event timing varies, timeouts are flaky
• Fix: Replaced timeouts with event-based waiting
• Files changed: agent-tool-abort.test.ts only
• All 3 tests now pass ✓

Agent 2 Findings:

• Root cause: Event payload structure changed in refactoring
• Old: { toolId, result }
• New: { threadId, toolId, result }
• Fix: Updated event emission to include threadId
• Files changed: batch-executor.ts, batch.service.ts
• Both tests now pass ✓

Agent 3 Findings:

• Root cause: Test asserted immediately, async execution still pending
• Fix: Added await waitForExecutionComplete() before assertions
• Files changed: tool-approval-race-conditions.test.ts only
• Test now passes ✓

Integration

Conflict check:

• Agent 1: Modified test file only
• Agent 2: Modified production files (batch executor)
• Agent 3: Modified test file only
• No overlaps detected ✓

Full suite verification:

npm test
# All tests pass ✓
# No new failures introduced ✓

Time analysis:

• Sequential approach: 60 minutes (3 × 20 min)
• Parallel approach: 25 minutes (20 min + 5 min integration)
• Time saved: 35 minutes (58% reduction)

Lessons Learned

1. Independence validation was correct - No hidden dependencies emerged 2. Scope boundaries held - Agents didn't overlap files 3. Clear prompts produced clear outputs - All agents returned usable summaries 4. Integration was trivial - No conflicts to resolve

Case Study 2: Multi-Subsystem Bug Fix

Scenario: Production incident affecting 3 subsystems

Initial State

Incident: User-reported issues across the platform

Symptoms:
- Users can't log in (Auth subsystem)
- Payments failing after login (Payment subsystem)
- Email confirmations not sending (Notification subsystem)

Decision Process

Question 1: Are these related?

• Login issue is auth-specific
• Payment failure might be due to login, or independent
• Email issue seems independent
• Answer: Unclear, need investigation ⚠️

Decision: Don't dispatch immediately, investigate first

Investigation Phase

Single agent task: Investigate all 3 issues for 15 minutes

Goal: Determine if shared root cause or independent bugs

Report back before we dispatch parallel fixes

Investigation Result:

Auth: Database connection pool exhausted
Payments: Independent bug - Stripe API version mismatch
Emails: Independent bug - SMTP credentials expired

Root cause analysis:
- Auth issue is systemic, affects all subsystems indirectly
- Payment and email issues are independent of auth
- BUT: Must fix auth first (it's blocking everything)

Revised Strategy

Phase 1: Fix auth (single agent, high priority)

Fix database connection pool exhaustion in auth subsystem
This is blocking other subsystems - highest priority

Phase 2: After auth fixed, dispatch parallel fixes

Agent 1: Fix Stripe API version mismatch in payment subsystem
Agent 2: Update SMTP credentials in notification subsystem

Execution

Phase 1 Result:

• Auth agent fixed connection pooling configuration
• All subsystems now accessible
• Time: 20 minutes

Phase 2 Dispatch:

• Agent 1 and 2 worked in parallel
• No dependencies between payment and email fixes
• Time: 15 minutes each (parallel)

Total time: 35 minutes (20 + 15) Sequential time would have been: 50 minutes (20 + 15 + 15) Saved: 15 minutes, but more importantly caught the systemic issue first

Lessons Learned

1. Investigation before dispatch is sometimes critical - Avoided wasting time on symptoms 2. Hierarchical dispatch works well - Fix blocker, then parallelize remaining work 3. Apparent independence can be misleading - Auth was blocking payment/email indirectly 4. Flexible strategy beats rigid process - Adapted approach based on findings

Case Study 3: Feature Development in Parallel

Scenario: New feature requires changes across 3 modules

Initial State

Feature: Add two-factor authentication

Required changes:
- Auth module: Add 2FA verification logic
- User module: Add 2FA preferences storage
- API module: Add 2FA setup/verify endpoints

Decision Process

Question 1: Are these independent?

• Auth verification logic is self-contained
• User preferences storage is independent
• API endpoints depend on both auth logic and user storage
• Answer: Partially independent ⚠️

Strategy: Parallel with coordination point

Execution

Phase 1: Parallel development of independent pieces

Agent 1: Implement 2FA verification logic (auth module)
- QR code generation
- TOTP token validation
- Backup codes

Agent 2: Implement 2FA preferences (user module)
- Database schema for 2FA settings
- Methods to enable/disable 2FA
- Backup code storage

Coordination Point:

Both agents complete and return:
- Agent 1: Exposes verify2FA(userId, token) interface
- Agent 2: Exposes get2FASettings(userId) interface

Review: Verify interfaces are compatible before API integration

Phase 2: Sequential API development

Agent 3: Implement API endpoints using Agent 1 & 2 interfaces
- POST /auth/2fa/setup
- POST /auth/2fa/verify
- GET /auth/2fa/status

This must be sequential - depends on previous work

Results

Time breakdown:

• Phase 1 (parallel): 45 minutes for both agents
• Coordination review: 5 minutes
• Phase 2 (sequential): 30 minutes
• Total: 80 minutes

Sequential would have been:

• Agent 1: 45 minutes
• Agent 2: 40 minutes
• Agent 3: 30 minutes
• Total: 115 minutes

Saved: 35 minutes (30% reduction)

Lessons Learned

1. Feature development can be parallelized - Even with dependencies 2. Interface coordination is critical - Reviewed compatibility before integration 3. Phased approach handles dependencies - Parallel where possible, sequential where necessary 4. Clear interface contracts enable parallel work - Agents didn't need to coordinate during implementation

Pattern Analysis

When Parallel Saves Time

High benefit scenarios:

✓ Many independent problems (5+)
✓ Each problem takes significant time (20+ min)
✓ Clear boundaries between domains
✓ Minimal coordination overhead
✓ Low risk of conflicts

Example: 5 test files failing, 30 min each = 150 min sequential
Parallel: 30 min + 10 min integration = 40 min
Savings: 110 minutes (73%)

Marginal benefit scenarios:

~ 2-3 problems
~ Each takes 10-15 minutes
~ Some shared boundaries
~ Need coordination

Example: 3 bugs, 15 min each = 45 min sequential
Parallel: 15 min + 10 min integration/coordination = 25 min
Savings: 20 minutes (44%)

No benefit scenarios:

✗ 1-2 quick problems (<10 min each)
✗ Highly related problems (shared root cause)
✗ Significant coordination needed
✗ High conflict risk

Example: 2 related bugs, 8 min each = 16 min sequential
Parallel: 8 min + 15 min coordination overhead = 23 min
Loss: -7 minutes

Real-World Time Savings

Project A: Test Suite Maintenance

Context: Weekly test maintenance for large codebase

Before parallel agents:

• 10-15 flaky tests per week
• Fixed sequentially: 4-5 hours
• Developer time: 1 person, full afternoon

After parallel agents:

• Same 10-15 flaky tests
• Fixed in parallel: 1-1.5 hours
• Developer time: 15 min dispatch + 15 min integration

Time saved per week: 3 hours Over 6 months: ~75 hours saved

Project B: Post-Refactoring Fixes

Context: Major refactoring broke 20+ tests

Sequential approach (previous experience):

• 1 developer, 2 full days (16 hours)
• High context switching cost
• Fatigue led to mistakes

Parallel approach (current):

• 5 agents, dispatched in 2 waves
• Wave 1: 5 agents × 1 hour = 1 hour
• Wave 2: 5 agents × 1 hour = 1 hour
• Integration: 30 minutes
• Total: 2.5 hours

Time saved: 13.5 hours (84% reduction) Quality improvement: Fewer mistakes (fresh agent context each time)

Project C: Multi-Subsystem Feature

Context: Payment system upgrade touching 8 modules

Sequential development estimate:

• 8 modules × 3 hours each = 24 hours
• 3 full days

Parallel approach:

• Grouped into 4 independent domains
• 4 agents × 3 hours = 3 hours
• Integration and testing: 2 hours
• Total: 5 hours

Time saved: 19 hours (79% reduction)

Anti-Pattern Examples

Anti-Pattern: Premature Parallelization

Scenario:

Developer: "I have 4 test failures, let me dispatch 4 agents immediately"

Result:
- Agent 1 discovers: Root cause is shared utility bug
- Agents 2, 3, 4 all hit the same bug
- All 4 agents report the same issue
- Wasted 3 agents' work

Better approach:

1. Quick investigation (5 min)
2. Identify shared root cause
3. Single agent fixes shared utility
4. All 4 tests pass
Total: 15 minutes vs 40+ wasted

Anti-Pattern: Over-Scoped Agents

Scenario:

Agent prompt: "Fix all the auth issues"

Result:
- Agent doesn't know where to start
- Changes 15 files
- Introduces new bugs
- Hard to review changes

Better approach:

3 focused agents:
- Agent 1: Fix login.test.ts (5 tests)
- Agent 2: Fix session.test.ts (3 tests)
- Agent 3: Fix oauth.test.ts (4 tests)

Each agent knows exactly what to do
Changes are reviewable
No new bugs introduced

Anti-Pattern: Ignoring Dependencies

Scenario:

Dispatch in parallel:
- Agent 1: Update User model
- Agent 2: Update Auth service (uses User model)
- Agent 3: Update Profile service (uses User model)

Result:
- Agent 1 changes User interface
- Agents 2 & 3 use old interface
- Massive integration conflicts

Better approach:

Phase 1: Agent 1 updates User model
Phase 2: Agents 2 & 3 in parallel update services
No conflicts, clean integration

Success Metrics

Quantitative Metrics

Time Efficiency:

Efficiency = 1 - (Parallel Time / Sequential Time)

Good: >60% (3+ independent problems)
Acceptable: 40-60% (2-3 problems with some coordination)
Poor: <40% (not worth parallelization overhead)

Conflict Rate:

Conflict Rate = Conflicts / Total Agents

Excellent: 0% (no conflicts)
Good: <10% (minor conflicts, easy resolution)
Acceptable: 10-20% (some conflicts, manageable)
Poor: >20% (significant coordination issues)

Qualitative Metrics

Agent Output Quality:

• Clear summaries provided: ✓
• Root causes identified: ✓
• Changes well-documented: ✓
• Verification performed: ✓

Integration Smoothness:

• No merge conflicts: ✓
• Compatible changes: ✓
• Full suite passes: ✓
• No regression introduced: ✓

Calculation Examples

Example 1: Simple Parallelization

Sequential:
- Problem A: 20 min
- Problem B: 20 min
- Problem C: 20 min
Total: 60 min

Parallel:
- All 3 agents: 20 min (concurrent)
- Integration: 5 min
Total: 25 min

Savings: 35 min (58%)

Example 2: With Dependencies

Sequential:
- Problem A (blocking): 30 min
- Problem B (depends on A): 20 min
- Problem C (depends on A): 20 min
Total: 70 min

Parallel:
- Phase 1 - Agent A: 30 min
- Phase 2 - Agents B & C: 20 min (concurrent)
- Integration: 5 min
Total: 55 min

Savings: 15 min (21%)

Example 3: Investigation + Fix

Sequential:
- Investigate: 15 min
- Fix problem A: 20 min
- Fix problem B: 20 min
- Fix problem C: 20 min
Total: 75 min

Parallel:
- Investigate (single agent): 15 min
- Based on findings, dispatch 3 agents: 20 min (concurrent)
- Integration: 5 min
Total: 40 min

Savings: 35 min (47%)

Troubleshooting

Complete guide to handling conflicts, verification strategies, and resolving common problems in parallel agent dispatch.

Conflict Detection

File-Level Conflicts

Symptom: Multiple agents modified the same file

Detection:

# After agent returns, check which files changed
git diff --name-only

# Compare with other agents' file lists
# If overlap exists → conflict potential

Resolution strategy:

Level 1: Non-overlapping changes
- Agent A changed lines 10-20
- Agent B changed lines 50-60
→ Git auto-merge handles this
→ Verify: Run tests after merge

Level 2: Nearby changes
- Agent A changed lines 10-20
- Agent B changed lines 25-35
→ Git might merge, but logic conflict possible
→ Verify: Review both changes for interaction
→ Test: Run full suite, check edge cases

Level 3: Overlapping changes
- Agent A changed lines 10-20
- Agent B changed lines 15-25
→ Git merge conflict
→ Verify: Understand both changes
→ Resolve: Manual merge or redesign

Logic-Level Conflicts

Symptom: No merge conflicts, but changes interact poorly

Example:

// Agent A changed function signature
function processPayment(userId, amount) { ... }
// Previously: processPayment(amount)

// Agent B added calls using old signature
processPayment(100); // Now breaks!

Detection strategy:

1. Review all agent summaries before integrating 2. Identify interface changes (function signatures, API contracts) 3. Check if other agents use those interfaces 4. Run full test suite after each integration 5. Watch for new failures in code you didn't touch

Prevention:

Agent prompts should specify:

Constraints:
- Do NOT change public interfaces without coordination
- Do NOT modify shared utilities
- If you must change a signature, report it before implementing

State-Level Conflicts

Symptom: Tests pass individually but fail when integrated

Example:

Agent A: Clears cache on startup
Agent B: Expects cache to be populated

Individually:
- Agent A tests: Cache clearing works ✓
- Agent B tests: Cache usage works ✓

Together:
- Agent B tests fail: Cache is empty ✗

Detection:

# Test each agent's changes in isolation
git checkout agent-A-branch
npm test # Pass ✓

git checkout agent-B-branch
npm test # Pass ✓

# Test integrated
git checkout integration-branch
npm test # Fail ✗ → State conflict detected

Resolution: 1. Understand state assumptions each agent made 2. Determine correct initialization order 3. Add explicit state setup in tests 4. Or refactor to remove shared state dependency

Verification Strategies

Strategy 1: Progressive Integration

Approach: Integrate one agent at a time, verify between each

# Start from clean main
git checkout main

# Integrate Agent 1
git merge agent-1-fixes
npm test # Verify Agent 1 only
# If pass: continue
# If fail: fix Agent 1 before integrating others

# Integrate Agent 2
git merge agent-2-fixes
npm test # Verify Agent 1 + 2
# If pass: continue
# If fail: identify which combination breaks

# Integrate Agent 3
git merge agent-3-fixes
npm test # Verify all 3

Benefits:

• Isolates which integration causes failures
• Easier to debug conflicts
• Clear rollback points

Cost:

• More integration steps
• Takes longer than all-at-once

Use when: High risk of conflicts, complex changes

Strategy 2: Parallel Verification

Approach: Verify each agent's changes in parallel, then integrate all

# Parallel verification (can run simultaneously)
# Terminal 1
git checkout agent-1-fixes
npm test # Verify Agent 1 in isolation

# Terminal 2
git checkout agent-2-fixes
npm test # Verify Agent 2 in isolation

# Terminal 3
git checkout agent-3-fixes
npm test # Verify Agent 3 in isolation

# After all pass individually
git checkout integration-branch
git merge agent-1-fixes agent-2-fixes agent-3-fixes
npm test # Verify integrated

Benefits:

• Fast verification of individual agents
• All agents validated before integration
• Clear that issues are integration-specific

Cost:

• Integration failures are harder to isolate
• Might need to back out and use progressive approach

Use when: Low risk of conflicts, well-scoped agents

Strategy 3: Staged Integration

Approach: Group related agents, integrate by groups

# Group 1: Test fixes (low conflict risk)
git merge agent-1-test-fixes agent-2-test-fixes
npm test

# Group 2: Implementation changes (higher conflict risk)
git merge agent-3-impl-changes
npm test

# Group 3: Refactoring (highest conflict risk)
git merge agent-4-refactor
npm test

Benefits:

• Balances speed and safety
• Groups likely-compatible changes
• Easier conflict isolation than all-at-once

Use when: Mixed risk levels across agents

Common Problems

Problem 1: Agent Changed Too Much

Symptom:

Agent task: "Fix login.test.ts (3 tests)"
Agent result: Changed 12 files, refactored auth module

Why this happened:

• Prompt was too vague
• No constraints specified
• Agent "improved" code beyond scope

Immediate fix: 1. Review changes - which are necessary for the task? 2. Extract only required changes 3. Discard "improvements" outside scope

Prevention:

Better prompt:

Fix the 3 failing tests in login.test.ts.

Allowed changes:
- login.service.ts (if bug found)
- login.test.ts (if test expectations wrong)

NOT allowed:
- Other files in auth module
- Refactoring
- Code style changes

Stay focused on making the 3 tests pass.

Problem 2: Agent Didn't Explain Changes

Symptom:

Agent: "Fixed the tests ✓"
You: "What did you change?"
Agent: [no summary provided]

Immediate fix: 1. Review git diff manually 2. Understand each change 3. Ask agent to explain (in follow-up)

Prevention:

Agent prompt must include:

Return:
- Root cause explanation
- List of files changed with brief explanation EACH
- How you verified the fix
- Any risks or edge cases

Do NOT just say "fixed" - I need to understand what changed.

Problem 3: Agents Have Conflicting Approaches

Symptom:

Agent A: Fixed race condition by adding mutex locks
Agent B: Fixed race condition by making operation synchronous

Both approaches work individually but conflict when integrated

Why this happened:

• Agents made independent architectural decisions
• No coordination on approach
• Both valid but incompatible

Resolution: 1. Evaluate approaches:

• Which is more aligned with codebase patterns?
• Which has better performance/correctness?
• Which has fewer side effects?

2. Choose one approach:

• Discard the other agent's changes
• Or merge best parts of both

3. Re-test with chosen approach:

• Verify all original issues resolved
• Ensure no new issues introduced

Prevention:

For architectural decisions, use two-phase approach:

Phase 1: Investigate and propose
- Agents research problem
- Agents propose solutions
- Coordinator reviews and aligns approaches

Phase 2: Implement approved solutions
- Agents implement with aligned approach
- No architectural conflicts

Problem 4: Integration Introduces New Failures

Symptom:

Agent 1 tests: Pass ✓
Agent 2 tests: Pass ✓
Agent 3 tests: Pass ✓

Integrated: Agent 1 & 2 tests pass, but Agent 3 tests fail ✗

Diagnosis process:

# Identify which combination breaks
git checkout main
git merge agent-1-fixes # Test → Pass ✓
git merge agent-2-fixes # Test → Pass ✓
# So far so good

git merge agent-3-fixes # Test → Fail ✗
# Agent 3 conflicts with Agent 1 + 2 integration

# Isolate the conflict
# Test Agent 3 with each individually
git checkout main
git merge agent-1-fixes agent-3-fixes # Test → ?
git checkout main
git merge agent-2-fixes agent-3-fixes # Test → ?

# Identify which specific interaction breaks

Common causes:

1. Initialization order dependency

   Agent 1 & 2 changed initialization order
   Agent 3 assumes old order
   → Solution: Update Agent 3 to new order

2. Shared state assumption

   Agent 1 & 2 now clear state between tests
   Agent 3 assumes state persists
   → Solution: Update Agent 3 to set up its state

3. Interface change

   Agent 1 changed function signature
   Agent 3 uses old signature
   → Solution: Update Agent 3 calls to new signature

Problem 5: Can't Reproduce Agent's Success

Symptom:

Agent: "All tests pass ✓"
You integrate: Tests fail ✗

Possible causes:

1. Agent ran subset of tests

   Agent ran: npm test login.test.ts
   You ran: npm test (all tests)

   Agent's tests pass, but broke other tests

2. Environment difference

   Agent: Used cached dependencies
   You: Fresh install

   Or vice versa

3. State pollution

   Agent: Tests passed in specific order
   You: Tests run in different order

   Agent's tests depend on state from previous tests

Debugging steps:

# 1. Exact reproduction
Run EXACTLY what agent ran:
- Same test command
- Same working directory
- Same git commit

# 2. Expand scope
Run broader test suite:
npm test # All tests
npm test --runInBand # Sequential execution
npm test --randomize # Random order

# 3. Clean environment
rm -rf node_modules package-lock.json
npm install
npm test

# 4. Check for state
npm test -- --forceExit # Kill process after tests
npm test -- --detectOpenHandles # Find state leaks

Verification Checklist

Pre-Integration

Before integrating any agent's work:

□ Agent provided clear summary of changes
□ Root cause explained and makes sense
□ Changed files list reviewed
□ Changes are within assigned scope
□ No unexpected files modified
□ No public interface changes (or coordinated if needed)
□ Agent verified their tests pass

During Integration

While integrating each agent:

□ Git merge conflicts resolved correctly
□ Both agents' logic preserved (not just picked one side)
□ Ran tests after resolving conflicts
□ No new warnings or errors introduced
□ Code style consistent (linting passes)

Post-Integration

After all agents integrated:

□ Full test suite passes
□ No new failures in unrelated tests
□ Performance hasn't degraded (if relevant)
□ All original issues resolved
□ No regressions introduced
□ Code review completed (if team process)

Recovery Procedures

Procedure 1: Rollback Individual Agent

When: One agent's changes cause issues

# Identify problematic agent
git log --oneline

# Revert that agent's merge
git revert -m 1 <merge-commit-hash>

# Or reset if not pushed yet
git reset --hard HEAD~1

# Re-test without that agent
npm test

# Fix or re-do that agent's work

Procedure 2: Start Over with Integration

When: Multiple conflicts, unclear which combination breaks

# Save all agent branches
git branch agent-1-fixes-backup agent-1-fixes
git branch agent-2-fixes-backup agent-2-fixes
git branch agent-3-fixes-backup agent-3-fixes

# Reset integration branch
git checkout integration
git reset --hard main

# Try progressive integration instead of all-at-once
# (See Strategy 1: Progressive Integration)

Procedure 3: Rebase and Retry

When: Conflicts due to diverged branches

# Update all agent branches from main
git checkout agent-1-fixes
git rebase main

git checkout agent-2-fixes
git rebase main

git checkout agent-3-fixes
git rebase main

# Now integrate with updated branches
# Conflicts should be reduced

Advanced Conflict Resolution

Conflict Type 1: Competing Implementations

Scenario:

// Agent A's approach: Add caching layer
async function fetchUser(id) {
  const cached = cache.get(id);
  if (cached) return cached;
  const user = await db.query(id);
  cache.set(id, user);
  return user;
}

// Agent B's approach: Optimize database query
async function fetchUser(id) {
  return await db.query(id, {
    include: ['profile', 'settings'] // Single query vs N+1
  });
}

Resolution: 1. Understand goals:

• Agent A: Reduce database load
• Agent B: Reduce query count

2. Evaluate compatibility:

• Can we do both?
• Are they solving same problem differently?

3. Best approach:

   // Combined: Optimized query + caching
   async function fetchUser(id) {
     const cached = cache.get(id);
     if (cached) return cached;
     const user = await db.query(id, {
       include: ['profile', 'settings']
     });
     cache.set(id, user);
     return user;
   }

Conflict Type 2: Test Expectations

Scenario:

// Agent A: Made function async
async function validateEmail(email) { ... }

// Agent B: Test expects synchronous
test('validates email', () => {
  const result = validateEmail('test@example.com');
  expect(result).toBe(true); // Fails: result is Promise
});

Resolution: 1. Identify which is correct:

• Should function be async? (Agent A)
• Or should test be updated? (Agent B)

2. Fix approach:

   // Update test to handle async
   test('validates email', async () => {
     const result = await validateEmail('test@example.com');
     expect(result).toBe(true);
   });

Conflict Type 3: Shared Utility Changes

Scenario:

// Shared utility
function formatDate(date) { ... }

// Agent A: Changed signature to add timezone
function formatDate(date, timezone) { ... }

// Agent B: Added calls without timezone
const formatted = formatDate(new Date()); // Breaks!

Resolution options:

Option 1: Backward compatible

function formatDate(date, timezone = 'UTC') {
  // Default timezone maintains backward compatibility
}

Option 2: Update Agent B's calls

// Find all Agent B's calls and update
const formatted = formatDate(new Date(), 'UTC');

Option 3: Coordination

Prevention: Agent prompts should say:
"Do NOT change shared utilities. If needed, coordinate first."

Monitoring Integration Health

Health Indicators

Green (healthy integration):

✓ All agents completed on time
✓ All summaries clear and detailed
✓ No file overlaps between agents
✓ All individual tests pass
✓ Full suite passes after integration
✓ No new warnings or errors
✓ Integration took <10 min

Yellow (caution):

⚠ Some agents took longer than expected
⚠ Minor file overlaps (non-conflicting)
⚠ Had to resolve 1-2 merge conflicts
⚠ Integration took 10-20 min
⚠ Found one unexpected test failure (quickly fixed)

Red (problematic integration):

✗ Multiple agents overlapped significantly
✗ Many merge conflicts
✗ Logic conflicts (no git conflicts but breaks)
✗ New test failures in unrelated code
✗ Integration took >30 min
✗ Had to rollback and restart

Post-Mortem Template

After problematic integration:

## What Went Wrong

[Describe the issue]

## Root Cause

[Why did this happen?]
- Unclear scope definition?
- Missed dependency?
- Agents made incompatible decisions?

## What We Learned

[Specific learnings from this incident]

## Prevention Strategy

[How to prevent this in future dispatches]
- Better prompt structure?
- More investigation before dispatch?
- Different grouping of problems?

## Action Items

[Concrete changes to process]

Best Practices

Do's

✓ Verify independence before dispatching ✓ Define clear scopes for each agent ✓ Request detailed summaries from agents ✓ Integrate progressively when high risk ✓ Test after each integration step ✓ Document conflicts and resolutions ✓ Learn from issues and improve process

Don'ts

✗ Don't dispatch without investigation if independence unclear ✗ Don't allow vague prompts ("fix the issues") ✗ Don't integrate blindly without reviewing summaries ✗ Don't skip verification steps to save time ✗ Don't ignore warning signs (overlapping files, etc.) ✗ Don't let agents change shared code without coordination ✗ Don't forget to run full suite after integration