dispatching-parallel-agents

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:

1. Verify the work — subagent reports describe intent, not necessarily what happened. Read the actual file changes or command output before accepting.
2. Check for conflicts — did two subagents edit the same file?
3. Run the affected test suites to confirm the integrated state passes
4. 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