tomevault-io 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
- Parallelization - Multiple investigations happen simultaneously
- Focus - Each agent has narrow scope, less context to track
- Independence - Agents don't interfere with each other
- Speed - N problems solved in time of 1
Navigation
Pattern Reference
- Coordination Patterns - Dispatch strategies, domain identification, integration workflows
Agent Management
- Agent Prompts - Prompt structure, templates, common mistakes, constraints
Learning Resources
- Examples - Real-world scenarios, case studies, time savings analysis
Problem Solving
- Troubleshooting - 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
- Independence is mandatory - Related failures need single-agent investigation
- Focus beats breadth - Narrow scope per agent prevents confusion
- Always verify integration - Don't blindly merge agent work
- Clear outputs required - Every agent returns summary of changes
- 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.