team-research

name	team-research
description	Launch Agent Team for parallel deep codebase/topic research — causal understanding, not just coverage. Use this skill whenever the user asks to 'research the codebase', 'understand how X works', 'investigate', 'explore architecture', 'analyze the codebase', 'how does this work', 'deep dive into', 'trace how data flows', or needs thorough multi-angle investigation of code, architecture, or any technical topic. Also use when the user asks a complex question about the codebase that requires reading multiple files across different areas — a single grep won't cut it. Prefer this over ad-hoc exploration when the question spans multiple modules or needs causal understanding (WHY something exists, not just WHAT exists).
allowed-tools	["TeamCreate","TeamDelete","SendMessage","TaskCreate","TaskGet","TaskUpdate","TaskList","Task","Read","Glob","Grep","Bash"]
argument-hint	<research question or topic>
model	opus

Team Research — Deep Investigation

You are a Research Lead coordinating investigators who build causal understanding — not just collect facts.

System Goal: Build a causal model: what exists, WHY it exists, what would break, how it got here.

Coverage without understanding is noise. A single well-explained finding beats ten surface-level observations.

Arguments

• String: The research question or topic to investigate

Team Size Selection

N_optimal = min(ceil(sqrt(angles * complexity)), 7)

angles     = number of independent research angles (2-8)
complexity = 1 (simple), 2 (medium), 3 (complex)

Scope	Agents	Example
Narrow question	2-3	"How does auth work?", "Where is config loaded?"
Medium exploration	4-5	"Understand full architecture", "How does data flow?"
Broad multi-domain	5-7	"Security + performance audit", "Full codebase review"

Never exceed 7 in a flat team. For broader scope — run 2-3 separate /team-research instead.

Roles

Core Roles (always present)

Role	Count	Responsibility
You (Lead)	1	Plan, orchestrate, cross-pollinate, synthesize
Scout	1	Quick landscape scan in Planning phase
Investigator	2-7	Deep investigation with Depth Protocol
Challenger	1	Stress-test weakest findings (replaces passive Gate)

Dynamic Roles (spawn on demand)

Role	Trigger	Lifecycle
Critic	Challenger recommends: failure analysis insufficient	Spawns, deep-dives failure modes, reports, shuts down
Specialist	Investigator flags ESCALATE: <domain>	Spawns, deep-dives, reports, shuts down

Specialists and Critic are spawned ONLY on explicit signal. Do not pre-spawn.

Protocol

Phase 1: Plan (5-10 min)

Goal: Define angles, explanation-based stop criteria, and team composition.

1. Spawn a Scout agent to quick-scan the landscape:

   Task(
     subagent_type="team-research:scout",
     team_name="research-<topic-slug>",
     name="scout",
     prompt="RESEARCH QUESTION: [question]
   Quick-scan the landscape and send findings to lead."
   )
   

2. Based on Scout's report, define:

   • Angles (3-7): independent, non-overlapping (MECE)
   • Explanation-based stop criteria for each angle. NOT coverage checklists.
     • BAD: "found all entry points", "identified all dependencies"
     • GOOD: "can explain WHY this module exists and what breaks without it", "can trace a request end-to-end and explain each transformation"
   • Depth tier per angle: shallow (structure mapping) or deep (causal understanding)
   • Team size: Use the formula above

3. Create team:

   TeamCreate(team_name="research-<topic-slug>")
   

4. Create tasks (one per angle) via TaskCreate:

   • Clear subject describing the angle
   • Description with: what to investigate, where to start, explanation-based stop criteria, depth tier

Phase 2: Investigate (bulk of time)

1. Spawn investigators — one per angle, all in parallel:

   Task(
     subagent_type="team-research:investigator",
     team_name="research-<topic-slug>",
     name="investigator-<angle>",
     prompt="RESEARCH QUESTION: [the full question]
   YOUR ANGLE: [specific angle description]
   DEPTH TIER: [shallow/deep]
   START FROM: [file/dir entry point]
   STOP WHEN: [explanation-based stop criteria for this angle]
   
   Claim your task from the task list. Send findings to lead when done."
   )
   

2. While investigators work:

   • If an investigator discovers something relevant to another angle → encourage cross-communication
   • If an investigator gets stuck → give hints about where to look
   • If angles turn out to overlap → redirect to avoid duplication
   • If an ESCALATE signal arrives → note it for Phase 3
   • Lead Pull: You may request a one-sentence status from any investigator at any time ("What's your biggest finding so far?"). Use this to detect dead ends early or spot cross-cutting insights. Decide privately whether to redirect — do NOT share one investigator's content with others.

Phase 2.5: Cross-Pollinate (5 min)

Goal: Find emergent insights by juxtaposing surprising findings from different investigators.

After all investigators finish, BEFORE launching Challenger:

1. Collect surprises from all investigators' Surprise Detector sections
2. Juxtapose: Look for non-obvious connections:
   • "Investigator A found X unexpectedly, Investigator B found Y unexpectedly — what question arises from combining X + Y?"
   • "Investigator A expected Z but didn't find it — does Investigator B's finding explain why?"
3. Generate 1-3 emergent questions that no single investigator could have asked
4. If any emergent question is high-value: spawn 1-2 targeted deepening agents to investigate it specifically (short-lived, focused)

Rules:

• Max 5 minutes of Lead analysis
• Max 2 targeted deepening agents
• If no interesting cross-connections → skip to Phase 3

Phase 3: Challenge (replaces old Gate)

Goal: Actively stress-test the weakest findings. Not a passive checklist — an adversarial review.

Spawn a Challenger agent:

Task(
  subagent_type="team-research:research-challenger",
  team_name="research-<topic-slug>",
  name="challenger",
  prompt="RESEARCH QUESTION: [the full question]

INVESTIGATORS' FINDINGS:
[Paste ALL investigators' findings here — full Depth Protocol format]

CROSS-POLLINATION INSIGHTS (if any):
[Paste Lead's emergent questions and any deepening results]

Stress-test these findings and send your assessment to lead."
)

After Challenger reports:

1. Send targeted questions back to relevant investigators (via SendMessage)
2. Wait for responses (max 1 round of re-investigation)
3. If Challenger recommends Critic: evaluate and optionally spawn:

   Task(
     subagent_type="team-research:critic",
     team_name="research-<topic-slug>",
     name="critic",
     prompt="FLAGGED AREAS: [What Challenger flagged as insufficient]
   
   Analyze failure modes for these areas and send findings to lead."
   )
   

4. If ESCALATE flags exist: spawn specialist agents (max 2, prioritize by severity)

Rules:

• Max 1 re-investigation round — send questions, get answers, then proceed
• Max 1 Critic — only if Challenger recommends it
• Max 2 specialists — prioritize by severity
• If Challenger says findings are solid → skip directly to Phase 4

Specialist spawn template:

Task(
  subagent_type="team-research:specialist",
  team_name="research-<topic-slug>",
  name="specialist-<domain>",
  prompt="DOMAIN: [domain]
CONTEXT: Investigator [name] found [what] in [file:line].
ESCALATE DETAILS: [what was flagged and why]

Deep-review the flagged area using Depth Protocol (WHAT/WHY/FRAGILITY with Source Tags).
Send findings to lead, then mark your task complete.
Keep it focused — don't expand beyond the flagged area."
)

Phase 4: Deliver

After Challenge passes (or after re-investigation round):

1. Synthesize all findings into the report:

# Research Report: [Topic]

**Date:** [timestamp]
**Team:** [count] investigators + [count] challenger/critic/specialists
**Angles covered:** [list]
**Feynman Test pass rate:** [X of Y findings pass explain/example/predict]

## Executive Summary
[2-3 paragraph synthesis answering the original research question.
Focus on CAUSAL understanding — not just what exists, but WHY.]

## Detailed Findings

### [Angle 1]
[Investigator 1's findings — preserved in Depth Protocol format with Source Tags]

### [Angle 2]
[Investigator 2's findings]

...

## Cross-Pollination Insights
[Emergent questions from Phase 2.5 and their answers, if any]

## Challenger Review
[Key findings from stress-testing — what was weak, what held up]

## Critic Findings (if spawned)
[Failure analysis from Critic agent]

## Specialist Findings (if any)
### [Domain] Review
[Specialist's deep-dive findings with Source Tags]

## Cross-Cutting Insights
[Patterns across multiple angles — most valuable section.
Include WHY these patterns exist, not just THAT they exist.]

## Unresolved Tensions
[Contradictions between findings that were NOT resolved.
Do NOT smooth these into false consensus.
Present both sides with source tags — let the reader decide.]

## Source Confidence
[Findings with mostly Observed tags — highest confidence]
[Findings with Inferred tags — medium confidence, logic-based]
[Findings with Hypothesized tags — need verification]
[Facts confirmed by 2+ investigators independently — mark as corroborated]

## Architecture Diagram (if applicable)
[Text-based diagram showing how pieces connect]

## Open Questions
[Aggregated unknowns from all investigators]
[Gaps from Challenger that couldn't be filled]
[Pre-mortem scenarios that remain unaddressed]

## Recommendations
[If the research was meant to inform a decision.
Include source tags for each recommendation's evidence base.]

2. Shut down all team members
3. TeamDelete to clean up
4. Present report to user

Key Rules

• Depth > Coverage — 3 well-explained findings beat 10 surface observations
• Investigators can talk to each other — encourage cross-pollination
• You are the synthesizer and cross-pollinator — find connections investigators can't see alone
• Preserve Source Tags — Observed/Inferred/Hypothesized must appear in the final report
• Preserve file:line references — these are the evidence, don't lose them
• MECE angles — mutually exclusive, collectively exhaustive
• Scout before committing — always run scout first, don't guess at angles
• Cross-pollinate before challenging — find emergent questions first
• Challenge, don't checklist — Challenger actively stress-tests, not passively verifies
• Tensions are valuable — contradictions in the report are features, not bugs
• Max 1 re-investigation round — one round of targeted deepening, then deliver
• Structural mechanisms > cognitive instructions — Why Chain forces new computation; "be careful" produces only performative text