| name | dispatching-parallel-agents |
| description | Use when facing 2+ independent problems with no shared state — e.g., unrelated test failures in different subsystems, multiple independent bug investigations, parallel research tasks. Dispatch one focused subagent per domain instead of investigating sequentially. |
Dispatching Parallel Agents — amd-smi
When you have multiple independent problems, sequential investigation wastes time. Dispatch one focused subagent per problem domain, integrate the results.
Core principle: One subagent per independent problem. Hand-craft each one's context — never let them inherit your session history.
When to Use
| Use when | Don't use when |
|---|
| 2+ test files fail with unrelated root causes | One failure may cascade into others |
| Independent subsystems broken (C lib + Python + CLI) by separate causes | You don't yet know what's broken |
| Multiple unrelated research questions | Investigation requires shared system state |
| Need to read/summarize many files in parallel | Agents would edit the same files |
Decision Flow
Multiple problems?
└─ Independent (no shared state, no cascade between them)?
├─ yes → dispatch one subagent per problem domain
└─ no → investigate together (single agent, full context)
The Pattern
1. Identify Independent Domains
Group failures or tasks by what's broken or what's being investigated. Each domain must be understandable without context from the others.
2. Craft Focused Subagent Prompts
Each prompt must contain:
- Scope — exactly one problem domain, one test file, or one subsystem
- Context — paste relevant error messages, file paths, line numbers, recent diffs
- Constraints — what the subagent must NOT touch
- Expected output — what the subagent must return (don't accept narrative summaries)
3. Dispatch Concurrently
Use the runSubagent tool, issuing all dispatches in the same response. Choose the most appropriate amd-smi review/development agent per task — don't default to the general-purpose agent if a specialized one exists.
4. Integrate Results
When subagents return:
- Verify the work — subagent reports describe intent, not necessarily what happened. Read the actual file changes or command output before accepting.
- Check for conflicts — did two subagents edit the same file?
- Run the affected test suites to confirm the integrated state passes
- If any subagent flagged a blocker → that branch of work stops until resolved; other branches may continue
Subagent Prompt Template
TASK: <specific problem in one sentence>
CONTEXT:
- Failing test: <path>:<line>
- Error message: <paste verbatim>
- Recent changes in this area: <git log oneline of last 3 commits touching this file>
- Related files: <paths>
CONSTRAINTS:
- Do NOT modify <list of files outside scope>
- Do NOT regenerate amdsmi_wrapper.py (it's auto-generated)
- Follow the project-layout rule
EXPECTED OUTPUT:
- Root cause (one paragraph)
- Files changed (list with line ranges)
- Verification command run and its output
- Any new findings/blockers
Common Mistakes
| ❌ Bad | ✅ Good |
|---|
| "Fix all the tests" | "Fix the 3 failures in tests/python_unittest/test_metrics.py" |
| Letting the subagent inherit your full session context | Hand-craft exactly the context the subagent needs |
| Trusting the subagent's "Done!" report | Read the diff and run the verification command yourself |
| Dispatching subagents to edit overlapping files | One subagent per file/subsystem; serialize edits to shared files |
| Dispatching for problems that might be related | Investigate together first; split only after confirming independence |
Verification After Integration
- Re-run the broader test suite (
amdsmi-test-runner), not just the per-subagent slice
- Check
git status for files no subagent claimed to touch
- Look for systematic errors — if two subagents made the same wrong assumption, the prompt template was the problem
Red Flags — STOP
- Subagent prompts that read "investigate X and fix anything related"
- Two subagents told to edit the same file
- No verification command in the prompt
- Accepting "looks good" without reading the diff
