| name | research |
| description | 10-team parallel deep analysis with cross-verification for any topic, repository, or technology. Use when user invokes /research or asks for comprehensive research. |
| scope | core |
| user-invocable | true |
| teams-compatible | true |
Research Skill
Orchestrates 10 parallel research teams for comprehensive deep analysis of any topic, GitHub repository, or technology. Produces a structured report with ADOPT/ADAPT/AVOID taxonomy.
Teams-compatible — works both from the main conversation (R010) and inside Agent Teams members. When used in Teams, the member directly executes the research workflow without Skill tool invocation.
Usage
/research <topic-or-url>
/research https://github.com/user/repo
/research "distributed consensus algorithms"
/research Rust async runtime comparison
When NOT to Use
| Scenario | Better Alternative |
|---|
| Simple factual question | Direct answer or single WebSearch |
| Single-file code review | /dev-review with specific file |
| Known solution implementation | /structured-dev-cycle |
| Topic with < 3 comparison dimensions | Single Explore agent |
Pre-execution check: If the query can be answered with < 3 sources, skip 10-team research.
Pre-flight Guards
Before executing the 10-team research workflow, the agent MUST run these checks. Research is a high-cost operation — these guards prevent wasteful execution regardless of the active model inventory.
Guard Levels
| Level | Meaning | Action |
|---|
| PASS | No issues detected | Proceed with research |
| INFO | Minor suggestion | Log note, proceed |
| WARN | Potentially wasteful | Show warning with cost estimate, ask confirmation |
| GATE | Wrong tool — use simpler alternative | Block execution, suggest alternative |
Guard 1: Query Complexity Assessment
Level: GATE or PASS
Check: Assess if the query requires multi-team research
# Simple factual questions → GATE
indicators_simple:
- Query is < 10 words
- Query asks "what is", "how to", "when was" (factual)
- Query has a single definitive answer
- Can be answered from a single documentation source
# Complex research questions → PASS
indicators_complex:
- Query involves comparison of 3+ alternatives
- Query requires analysis across multiple dimensions
- Query mentions "compare", "evaluate", "analyze", "research"
- Query references a repository or ecosystem for deep analysis
Action (GATE): [Pre-flight] GATE: Query appears to be a simple factual question. Use a direct answer or one search instead. A 10-team research run would be wasteful. Override with /research --force if intended.
Guard 2: Single-File Review Detection
Level: GATE
Check: If the query references a single file for review
# Detection
- Query mentions a specific file path (e.g., src/main.go)
- Query asks to "review" or "analyze" a single file
- No broader context requested
Action: [Pre-flight] GATE: For single-file review, use /dev-review {file} instead. Research is for multi-source analysis.
Guard 3: Known Solution Detection
Level: INFO
Check: If the query is about implementing a known solution
# Detection
keywords: implement, build, create, add feature, 구현, 만들어
# AND the solution approach is well-known (not requiring research)
Action: [Pre-flight] INFO: If the implementation approach is already known, consider /structured-dev-cycle instead of research. Proceeding with research.
Guard 4: Context Budget Check
Level: WARN
Check: Estimate context impact of 10-team research
CONTEXT_FILE="/tmp/.codex-context-$PPID"
if [ -f "$CONTEXT_FILE" ]; then
context_pct=$(cat "$CONTEXT_FILE")
if [ "$context_pct" -gt 40 ]; then
fi
fi
Action: [Pre-flight] WARN: Context usage at {pct}%. 10-team research typically adds 30-40% context. Consider /compact before proceeding, or results may be truncated.
File-absent branch (#1466): $CONTEXT_FILE가 존재하지 않으면 입력이 측정 불가하다 — PASS (context budget unmeasured — file absent)로 보고하고 WARN을 내지 않는다. 파일을 읽지 않고 WARN 상태를 특성화하지 않는다(R020 Read-Before-Characterize). WARN은 파일이 존재하고 context_pct > 40일 때만 emit한다.
Display Format
[Pre-flight] research
├── Query complexity: PASS — multi-dimensional comparison detected
├── Single-file review: PASS
├── Known solution: PASS
└── Context budget: WARN — context at 45%, research adds ~35%
Result: PROCEED WITH CAUTION (0 GATE, 1 WARN, 0 INFO)
Cost: runtime-dependent; bounded by 10 teams and the verification-round cap
If any GATE: block and suggest alternative. User can override with --force.
If any WARN: show warning with cost context, ask user to confirm.
If only PASS/INFO: proceed automatically.
Architecture — 4 Phases
Phase 1: Parallel Research (10 teams, batched per R009)
Step 0: Pre-flight guards pass (see Pre-flight Guards section)
Teams operate in breadth/depth pairs across 5 domains:
| Pair | Domain | Team | Role | Focus |
|---|
| 1 | Architecture | T1 | Breadth | Survey, catalog, enumerate structure |
| | T2 | Depth | Deep-dive patterns, validate assumptions |
| 2 | Security | T3 | Breadth | Vulnerability scan, attack surface enumeration |
| | T4 | Depth | Exploit validation, risk quantification |
| 3 | Integration | T5 | Breadth | Compatibility mapping, dependency analysis |
| | T6 | Depth | Effort estimation, value assessment |
| 4 | Comparative | T7 | Breadth | Alternative survey, market landscape |
| | T8 | Depth | Feature comparison, benchmark data |
| 5 | Innovation | T9 | Breadth | Novel pattern identification, idea extraction |
| | T10 | Depth | Feasibility validation, adaptation design |
Batching order (max 4 concurrent per R009):
Batch 1: T1, T2, T3, T4 (Architecture + Security)
Batch 2: T5, T6, T7, T8 (Integration + Comparative)
Batch 3: T9, T10 (Innovation)
Phase 2: Cross-Verification Loop (min 2, max 30 rounds)
Codex Availability Check
Before starting verification rounds, check codex availability:
Team findings ──→ verifier (`frontier`/`high`) ──→ optional plugin-assisted verification
│ │
└── Contradiction detected? ── YES ──→ Round N+1
NO ──→ Consensus reached → Phase 3
Each round:
- Verifier (
frontier/high): Checks logical consistency, identifies gaps, and challenges assumptions
- Optional Codex interop: Use native Claude Code plugin
openai/codex-plugin-cc only when explicitly installed/requested; otherwise use researcher or RTK-backed local evidence gathering.
- Contradiction resolution: Reconcile divergent findings between teams and verifiers
- Convergence check: All major claims verified with no outstanding contradictions → proceed
Convergence expected by round 3. Hard stop at round 30.
Phase 3: Synthesis
- Cross-team gap analysis — identify areas no team covered
- Unified priority ranking — weight findings by confidence and impact
- ADOPT / ADAPT / AVOID taxonomy generation
Phase 4: Output
- Structured markdown report (see Output Format below)
- Artifact persistence: The Phase 4 synthesis agent (frontier/high) writes the report to:
.codex/outputs/sessions/{YYYY-MM-DD}/research-{HHmmss}.md
Compatibility artifact protocol
Sensitive-path compatibility note: when delegated work touches .claude/outputs/, .claude/**, or templates/.claude/**, keep .codex/** artifacts on the normal file-write path. On Claude Code v2.1.121+ with bypassPermissions, direct compatibility writes are allowed for .claude/skills/, .claude/agents/, and .claude/commands/; on v2.1.126+ broader protected paths are covered. Use /tmp/<skill>-<timestamp>.md only as a legacy fallback when the runtime is older or still prompts.
With metadata header:
```markdown
---
skill: research
date: {ISO-8601 with timezone}
query: "{original user query}"
---
The agent writes the artifact file using a file-write API that creates missing parent directories; do not run any Bash directory-creation pre-step for session outputs (R010 compliance).
Sensitive-path compatibility note: delegated research agents should keep .codex/** artifacts on the normal write path and use /tmp/research-{timestamp}.md only as a legacy fallback when an older Claude Code runtime still prompts on compatibility paths.
3. GitHub issue auto-created with findings
4. Action items with effort estimates
Execution Rules
| Rule | Detail |
|---|
| Max parallel teams | 4 concurrent (R009) |
| Batching | T1-T4 → T5-T8 → T9-T10 |
| Agent Teams gate | If enabled, use for cross-team coordination (R018) |
| Orchestrator only | Main conversation manages all phases (R010) |
| Ecomode | Auto-activate for team result aggregation (R013) |
| Intent display | Show research plan before execution (R015) |
External Quantitative-Fact Source Tagging
Research teams that collect concrete quantitative claims (benchmark numbers, table values, metrics) via WebFetch must tag them in synthesis/report output as WebFetch-derived (unverified) unless independently verified from a primary source such as the PDF/original paper. Multiple teams fetching the same URL can share the same WebFetch cache artifact, so agreement across those fetches is not independent ground-truth. Do not write exact load-bearing numbers into persistent issues/artifacts as fact without primary-source verification or an explicit unverified tag (R020, R023).
Retrieval-Reasoning Separation
Retrieval and reasoning are distinct cognitive operations that benefit from explicit role separation. Mixing them in a single agent degrades both: retrieval becomes biased by premature conclusions, and reasoning gets polluted by search noise.
Principle
| Role | Phase | Lane / Effort | Responsibility |
|---|
| Retriever | Phase 1 | frontier/medium (fast, broad) | Gather, catalog, enumerate — no judgment |
| Reasoner | Phase 2-3 | frontier/high (deep, precise) | Verify, synthesize, judge — no new retrieval |
Why Separate
- Retrieval bias: A reasoning agent searching for evidence tends to confirm existing hypotheses (confirmation bias)
- Context pollution: Raw search results mixed with analysis obscure both
- Cost efficiency: Retrieval needs speed and breadth (cheaper model); reasoning needs depth (capable model)
- Debuggability: When results are wrong, separated roles make it clear whether the problem was bad retrieval or bad reasoning
Application in Research Workflow
| Phase | Role | Separation Rule |
|---|
| Phase 1 (10 teams) | Retriever | Teams gather and catalog only. No ADOPT/AVOID judgments. |
| Phase 2 (Verification) | Reasoner | Verifiers challenge claims using Phase 1 data. No new searches. |
| Phase 3 (Synthesis) | Reasoner | Synthesizer produces taxonomy from verified findings only. |
| Phase 4 (Output) | Reporter | Formats and persists. No new analysis. |
Model Selection
| Phase | Lane / Effort | Rationale |
|---|
| Phase 1 (Research teams) | frontier/medium | Balanced speed/quality for parallel research |
| Phase 2 (frontier/high verification) | frontier/high | Deep reasoning for cross-verification |
| Phase 2 (code verification) | frontier/xhigh | Code-level validation of technical claims |
| Phase 3 (Synthesis) | frontier/high | Complex multi-source reasoning and taxonomy |
Team Prompt Templates
Breadth Teams (T1, T3, T5, T7, T9)
Role: {domain} breadth analyst
Scope: {topic}
Tasks:
1. Survey the full landscape of {focus area}
2. Catalog all {artifacts/components/alternatives} found
3. Enumerate {structure/surface/compatibility/options/patterns}
4. Produce structured inventory with confidence levels
Output format:
- Inventory table (item | description | confidence)
- Coverage map (what was examined vs what remains)
- Key observations (max 5)
- Questions for depth team
Depth Teams (T2, T4, T6, T8, T10)
Role: {domain} depth analyst
Scope: {topic}
Tasks:
1. Deep-dive into {specific patterns/risks/efforts/benchmarks/feasibility}
2. Validate assumptions from breadth analysis (if available)
3. Quantify {quality/risk/effort/performance/value}
4. Produce evidence-backed assessment
Output format:
- Detailed analysis (claim | evidence | confidence)
- Validated/invalidated assumptions
- Quantified metrics where possible
- Risk/opportunity assessment
Verification Loop Detail
Round N:
Input: All 10 team findings + previous round feedback (if any)
Step 1: frontier/high reviews each team pair for:
- Internal consistency (breadth ↔ depth alignment)
- Cross-domain consistency (security ↔ architecture)
- Evidence quality (claims without backing)
Step 2: Optional plugin-assisted validation (only if `openai/codex-plugin-cc` is explicitly installed/requested):
a. Validate technical claims against code patterns, benchmark reproducibility,
and dependency resolution.
b. Parse contradictions → merge with verifier findings.
c. On unavailable plugin or error: log "[Phase 2] Round {N}: optional interop unavailable — continuing with verifier/researcher results".
Step 3: Compile contradiction list
- 0 contradictions → CONVERGED
- >0 contradictions → feedback to relevant teams → Round N+1
Output Format
# Research Report: {topic}
## Executive Summary
{2-3 paragraph overview of findings, key recommendation, confidence level}
## Team Findings
### Architecture (Teams 1-2)
**Breadth**: {inventory summary}
**Depth**: {analysis summary}
**Confidence**: {High/Medium/Low}
### Security (Teams 3-4)
**Breadth**: {attack surface summary}
**Depth**: {risk assessment summary}
**Confidence**: {High/Medium/Low}
### Integration (Teams 5-6)
**Breadth**: {compatibility summary}
**Depth**: {effort/value summary}
**Confidence**: {High/Medium/Low}
### Comparative (Teams 7-8)
**Breadth**: {landscape summary}
**Depth**: {benchmark summary}
**Confidence**: {High/Medium/Low}
### Innovation (Teams 9-10)
**Breadth**: {pattern summary}
**Depth**: {feasibility summary}
**Confidence**: {High/Medium/Low}
## Cross-Verification Results
**Rounds completed**: {N}
**Contradictions found**: {count}
**Resolution**: {summary of how contradictions were resolved}
## Taxonomy
### ADOPT (Safe + High Value)
| Item | Rationale | Confidence |
|------|-----------|------------|
### ADAPT (Valuable but needs modification)
| Item | Required Changes | Effort |
|------|-----------------|--------|
### AVOID (Risk > Value)
| Item | Risk | Alternatives |
|------|------|-------------|
## Action Items
| # | Item | Effort | Priority | Owner |
|---|------|--------|----------|-------|
Post-Research Advisory
After research completion, the orchestrator SHOULD display:
[Advisory] Research complete.
├── For complex implementations (10+ files): /structured-dev-cycle
├── For quick planning: EnterPlanMode (plan mode)
└── For simple tasks (< 3 files): proceed directly
This advisory is informational only and does not block execution.
Fallback Behavior
| Scenario | Fallback |
|---|
| Optional Codex plugin unavailable | researcher plus frontier/high verifier (still min 2 rounds) |
| Agent Teams unavailable | Standard Agent tool with R009 batching |
| Partial team failure | Synthesize from available results, note gaps in report |
| GitHub issue creation fails | Output report to conversation only |
Display Format
Before execution:
[Research Plan] {topic}
├── Phase 1: 10 teams (3 batches × 4/4/2)
├── Phase 2: Cross-verification (2-5 rounds, verifier + code evidence)
├── Phase 3: Synthesis (frontier/high)
└── Phase 4: Report + GitHub issue
Estimated: {time} | Teams: 10 | Routing: researcher/medium → verifier/high → code evidence
Stopping: max 30 verification rounds, convergence at 0 contradictions
Cost: runtime-dependent; bounded by team and round limits
Execute? [Y/n]
Progress:
[Research Progress] Phase 1 — Batch 2/3
├── T1-T4: ✓ Complete
├── T5-T8: → Running
└── T9-T10: ○ Pending
Teams Mode
When running inside an Agent Teams member (not via Skill tool), the research workflow operates identically but with these adaptations:
How It Works
The orchestrator reads this SKILL.md and includes the research instructions directly in the Teams member's prompt. The member then:
- Executes Phase 1-4 autonomously using its own Agent tool access
- Spawns research teams as sub-agents (Teams members CAN spawn sub-agents)
- Delivers results via
SendMessage to the team lead instead of returning to orchestrator
Prompt Embedding Pattern
# When spawning a Teams member for research:
Agent(
name: "researcher-1",
team_name: "my-team",
prompt: """
You are a research agent. Follow the research skill workflow below:
{contents of research/SKILL.md}
Topic: {user's research topic}
Deliver results via SendMessage to team lead when complete.
"""
)
Differences from Orchestrator Mode
| Aspect | Orchestrator Mode | Teams Mode |
|---|
| Invocation | Skill(research) | Prompt embedding |
| Result delivery | Return to main conversation | SendMessage to team lead |
| Artifact persistence | Teams member writes artifact | Same |
| GitHub issue creation | Orchestrator handles | Teams member handles directly |
| Phase management | Orchestrator manages phases | Member manages phases autonomously |
Constraints
- Each Teams member running research still respects R009 (max 4 concurrent sub-agents)
- Batching order remains: T1-T4 → T5-T8 → T9-T10
- Cost shape is identical to orchestrator mode and depends on the active OMX model inventory
- Multiple Teams members running research simultaneously will multiply costs proportionally
Integration
| Rule | Integration |
|---|
| R009 | Max 4 parallel teams; batch in groups of 4/4/2 |
| R010 | Orchestrator manages all phases; teams are subagents |
| R013 | Ecomode auto-activates for 10-team aggregation |
| R015 | Display research plan with team breakdown before execution |
| R018 | Agent Teams for cross-team coordination if enabled |
| dag-orchestration | Phase sequencing follows DAG pattern |
| result-aggregation | Team results formatted per aggregation skill |
| multi-model-verification | Phase 2 uses multi-model verification pattern |
Claude compatibility Agent calls only (R010 “Delegated Permission Ownership”): Pass mode: "bypassPermissions" when the active Claude session uses bypass permissions. Native Codex spawn_agent has no mode parameter; use the installed agent_type and active Codex runtime permissions instead.
