# Team Research

> 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).

- Skill: `izmailovilya/team-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add izmailovilya/team-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/izmailovilya/team-research/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: izmailovilya (https://skillmd.com/u/izmailovilya)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/izmailovilya/team-research

---


# 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."
)
```

<!-- report-format-contract -->
### Output format: the "now → after" table

The report is read by a product person, not an engineer. Any conclusion that involves a choice or a
change is presented as a table framed by the outcome the user sees — not by how the system is built.

**When there is a fork (something must be chosen):**

| What the person does | Now | Option A: "name" | Option B: "name" |
|---|---|---|---|
| ordinary situation | what they see today | what they'd see | what they'd see |
| edge case, error | ... | ... | ... |

Below the table, a "Why" block: one line per option (what it wins, what it costs). Then one line:
"Recommend X, because …".

**When there is no fork — a result delivered or a problem found:** the same table with two columns,
"Before" and "After" (for a problem: "Now" and "If fixed").

Rules for filling it in:

- Rows are real user situations, never system components. "Scanned a barcode and typed 73 g", not
  "the barcode_service handler".
- Cells say what the person will see, concretely and with numbers: "calories for 60 g instead of 73",
  not "incorrect calculation".
- The "Now" column is mandatory — without a baseline the options have nothing to compare against. If
  the thing doesn't exist yet, write "doesn't exist".
- Include at least one edge-case row: typo, empty input, error. That is usually where the options
  actually diverge.
- 2-4 rows, 2-3 options. More means the thinking isn't finished and the choice is being dumped on the
  reader.
- Name options by meaning ("trust the person" / "trust the package"), never "Option 1/2".

No fork and no change means no table: one line saying what you're doing and why. Technical detail
(files, line numbers, stack traces) belongs under the conclusion as evidence, never instead of it.
Write the table in the language the user is speaking.

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