team-research

What this skill does

# 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:

```markdown
# 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 spawne