• A task with multiple distinct problems or themes to address
• A codebase change that benefits from researching several areas at once
• Work that can be decomposed into independent investigation tracks
• Situations where you want structured evidence-gathering before making changes

1. Parse the user's input to identify distinct problems or themes
2. If the problems are ambiguous or underspecified, ask clarifying questions before proceeding
3. Group related problems into 2-5 investigation tracks (one per teammate)
4. Present the decomposition to the user:
   • List each track with its assigned problems
   • Name each teammate descriptively (e.g.,

     filter-investigator

     ,

     output-researcher

     )
   • Ask: "I'll spin up N investigators in parallel. Proceed?"

1. Create a team with

   TeamCreate

2. Create tasks for each investigation track with

   TaskCreate

3. Spawn one

   general-purpose

   teammate per track using

   Task

   with

   team_name

   • Each teammate's prompt must include:
     • The specific problems to investigate
     • Instruction to research only, do not make changes
     • The subagent guidance below (copy it into their prompt)
     • Instruction to report findings via

       SendMessage

       using the report format below
   • Spawn all investigators in parallel — do not wait for one to finish before starting the next
4. Do NOT shut down investigators when they report back — they retain context for Phase 4

Use subagents (

Task

tool) to keep your context focused. Spawn subagents for:

• Exploring specific files, modules, or subsystems
• Searching through git history, logs, or large codebases
• Any research tangent that might not pan out

Each subagent should report back:

1. Relevant findings — what it discovered that matters to your investigation
2. Red herrings (1-2 sentences) — anything that looks related but isn't, and why. Calling these out early prevents wasted cycles re-exploring dead ends.

Report red herrings even when your main findings are conclusive — they prevent other agents from re-exploring the same dead ends.

After receiving a subagent's report, decide whether to:

• Use its findings directly — if the summary gives you enough to proceed
• Dive in yourself — if the subagent found something promising and you want full, first-hand context in that area before drawing conclusions. Examples: conflicting evidence that needs direct examination, low confidence in the subagent's assessment, or complex state/flow where first-hand context matters.

When choosing subagent types, prefer read-only or exploration-focused types for open-ended codebase searches, and full-capability types for targeted analysis that needs deeper tool access.

• {what was discovered, root causes, relevant code paths}

• {what to change, which files, how}

• {what could go wrong with this approach}
• {what adjacent code/features could be affected}
• {what happens if data is unexpected or flow is interrupted}

• {things explored that weren't relevant, and why}

• {does this approach depend on or conflict with other tracks?}

undefined

1. As investigators report back, give the user brief progress updates — don't wait silently for all of them
2. Once all investigators have reported, synthesize findings:
   • Key findings per track
   • Proposed approaches and confidence levels
   • Any conflicts or dependencies between tracks
   • Ripple effects — Evaluate across all tracks:
     • "What happens to..." — documentation, adjacent features, API consumers, shared state, caching
     • "What happens if..." — unexpected data, interrupted flows, concurrent access, rollback
   • Recommended implementation order (dependencies first, then highest-risk, then the rest)
3. If investigation reveals the problem is different than expected, say so — propose revised tracks rather than forcing the original plan
4. Ask the user: "Ready to implement, or want to revise the approach?"

• Mixed, unrelated work in a single commit
• Confusing build/test failures caused by concurrent changes in flight
• File conflicts when teammates touch shared code

1. For each track (in the order agreed with the user):
   • Message the original investigator to begin implementation via

     SendMessage

   • Assign their implementation task via

     TaskUpdate

   • Include the subagent guidance for implementation below in your message
   • When starting subsequent tracks, forward the previous track's "what changed" summary so the investigator has implementation context, not just investigation context
   • Wait for completion before starting the next track
   • After each track completes, have the teammate report what changed
   • Run relevant tests/checks as a quick sanity check before moving to the next track
2. Parallel exception: Only consider parallel implementation if tracks have zero file overlap AND the codebase has no shared build/test pipeline that could produce confusing interleaved failures. If you think parallel is safe, explain why and ask the user.
3. Partial failures:
   • If an investigator reported low confidence or found nothing actionable, discuss with the user before implementing — options are to drop the track, merge it into another, or investigate further
   • If implementation fails mid-track, stop and discuss with the user whether to roll back or adjust the approach before continuing to the next track

Use subagents to keep your main context focused on implementation logic. Spawn subagents for:

• Repetitive edits — similar changes across many files (updating imports, renaming across test files, applying a pattern to multiple modules)
• Impact analysis — finding all callers of a function before changing its signature, checking all consumers of an API
• Exploratory reading — checking whether a module's assumptions break with your change, verifying edge cases in adjacent code
• Background test runs — running tests while you continue working on the next change

1. Spawn a fresh

   general-purpose

   teammate named

   validator

   . The validator's spawn prompt must include: the original problems from Phase 1, the agreed implementation approach from Phase 3, and risk areas flagged by investigators. Instruct the validator to:
   • Detect the project's test/lint/typecheck tooling and run appropriate checks
   • Review all changed files for correctness and consistency
   • Check that each problem from Phase 1 is actually addressed
   • Look for unintended side effects or regressions
   • Report pass/fail with details via

     SendMessage

2. If validation fails:
   • Route failures back to the responsible investigator for fixes
   • Re-run validation after fixes
3. Once validation passes, shut down all teammates and report results to the user

• Investigate in parallel, implement in series — research benefits from parallelism; implementation benefits from sequencing
• Subagents are cheap, context is expensive — teammates should offload research tangents and repetitive edits to subagents rather than doing everything inline
• 3-5 teammates max — if more problems than that, group into themes
• Never

  git add .

  — teammates must add specific files
• Validator is always fresh — do not reuse an investigator as validator
• If a teammate goes idle, that's normal — send them a message when it's their turn