Research

Research

Structured multi-viewpoint research on a given topic. Spawns 5 Sonnet sub-agents in parallel, each analyzing from a distinct analytical viewpoint, then synthesizes into a single research document.

---

When to Use This Skill

Load this skill when the user request matches ANY of these patterns:

| Trigger Pattern | Example User Request | |-----------------|---------------------| | Deep research | "Research agent teams", "Investigate loop detection" | | Topic exploration | "What do we know about X?", "Explore approaches to Y" | | Pre-planning research | "Before we build X, research the landscape" | | Multi-viewpoint analysis | "Analyze X from multiple angles" |

DO NOT use for:

• Evaluating implementation feasibility (use brainstorm)
• Quick fact lookup (use web search or codebase exploration)
• Code review (use code-review)
• Debugging (use issue-debugging)

---

Dependencies

| Category | Files | Requirement | When to Load | |----------|-------|-------------|--------------| | Viewpoint definitions | references/viewpoint-*.md | REQUIRED | Always load all 5 before spawning agents | | Output templates | templates/viewpoint-output.md | REQUIRED | Include in every agent prompt | | Synthesis template | templates/synthesis-output.md | REQUIRED | Use when writing synthesis | | Subagent prompting | subagent-prompting skill | REQUIRED | Load at Stage 1 for 4-part prompt template |

Fallback behavior:

• If a viewpoint reference file is missing: Note in diagnostic log, reduce to 4 agents, continue
• If output template is missing: Use the schema from this SKILL.md directly

---

Usage

/research  [--context ]
/research --doc 

Arguments:

• `` - Free-text topic description or problem statement
• --context - Additional context file to provide to all agents
• --doc - Use a document as the topic source instead of free text

Examples:

• /research "agent teams and multi-agent orchestration" - Research a topic
• /research --doc plans/proposal.md - Research from a document
• /research "loop detection" --context docs/architecture.md - Research with context

---

Stages

Stage 1: Pre-Flight

Stage 1: Pre-Flight
├── Read problem statement / document
├── AskUserQuestion if ambiguous (iterative, 2-3 questions per round)
├── Slugify topic for output directory
├── Create output directories: $PROJECT_DIR/logs/research/{topic-slug}/ and $PROJECT_DIR/artifacts/research/{topic-slug}/
├── Load subagent-prompting skill
├── Load all 5 references/viewpoint-*.md
├── Load templates/viewpoint-output.md
└── Token budget check (warn if >30% consumed)

AskUserQuestion Protocol (Pre-Spawn):

If the problem statement is ambiguous, under-specified, or could benefit from scope boundaries:

1. Ask 2-3 clarifying questions using AskUserQuestion
2. Assess whether the answers provide sufficient clarity to construct high-quality prompts
3. If not, ask up to 3 more questions in a follow-up round
4. Repeat until clarity is achieved (no hard cap on rounds, but each round is 2-3 questions max)
5. If the problem statement is clear and well-scoped from the start, skip this step and note in diagnostics: pre_flight_interview: skipped (problem statement sufficient)

Stage 2: Viewpoint Analysis (5 Sonnet, Parallel)

Stage 2: Viewpoint Analysis
├── Construct 5 prompts using 4-part template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
├── Each prompt includes:
│   ├── Viewpoint definition from references/viewpoint-{name}.md
│   ├── Output template from templates/viewpoint-output.md
│   ├── Topic description + any user-provided context
│   └── Output path: $PROJECT_DIR/logs/research/{topic-slug}/{NN}-{viewpoint-slug}.md
├── Spawn all 5 agents in parallel via Task tool
│   ├── subagent_type: general-purpose
│   ├── model: sonnet
│   └── All 5 in a single message (parallel)
└── Token budget check after all 5 complete (checkpoint if >55%)

CRITICAL: Spawn all 5 agents in a single message with 5 Task tool calls. Do NOT spawn sequentially.

Stage 3: Synthesis

Stage 3: Synthesis
├── Read ALL 5 agent output files (MANDATORY — do not skip any)
├── If any output is missing or empty → re-spawn that agent once (max 1 retry)
├── If retry fails → document gap in synthesis under "Incomplete Coverage"
├── Load templates/synthesis-output.md
├── Write synthesis to $PROJECT_DIR/artifacts/research/{topic-slug}/synthesis.md
├── AskUserQuestion for user on open questions (iterative, 2-3 per round)
├── Critical Evaluation Gate (see below)
└── Token budget check (must be  "Your suggestion about [X] is unvalidated. I recommend a targeted follow-up research phase with 2 focused agents (Direct Investigation + Contrarian) to verify feasibility and surface risks before incorporating this into the synthesis.
>
> This will spawn 2 Sonnet agents and consume additional token budget.
>
> [Run follow-up research / Incorporate as-is with LOW confidence caveat]"

**Step 3 — If follow-up research approved:**

1. Spawn 2 Sonnet agents in parallel (single message, 2 Task tool calls):
   - **Direct Investigation** — focused on validating the specific claim/solution
   - **Contrarian** — focused on finding failure modes and alternatives for the specific claim/solution
2. Use the same 4-part prompt template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
3. Include the REASONING DEPTH instructions from the viewpoint reference docs
4. Output to: `$PROJECT_DIR/logs/research/{topic-slug}/followup-{NN}-direct-investigation.md` and `followup-{NN}-contrarian.md`
5. Read both outputs, then update synthesis with validated findings
6. Tag follow-up findings in synthesis with: `[Follow-up: validated]` or `[Follow-up: refuted]` or `[Follow-up: mixed — see details]`

**Step 4 — If user declines follow-up:**

Incorporate the user's suggestion into synthesis with an explicit caveat:
> **[Unvalidated — user suggestion, not research-backed]**: {suggestion}

**Repeat**: After updating synthesis, ask if user has additional questions or input. Apply the same classification gate to each round. There is no limit on follow-up rounds, but each round with Speculative input that triggers research consumes ~10-15% token budget — warn user if approaching 60%.

### Stage 4: Diagnostics (REQUIRED)

Stage 4: Diagnostics ├── Write diagnostic YAML to $PROJECT_DIR/logs/diagnostics/research-{YYYYMMDD-HHMMSS}.yaml └── Verify completion checklist

---

## Viewpoints (Sections)

Each viewpoint is a distinct analytical lens. All 5 run in parallel — they do not see each other's output.

### Viewpoint 1: Direct Investigation

**Core Question**: What is this? How does it work? State of the art?

**Focus Areas**:
- Precise definition — what it is and what it is not
- Mechanical operation (architecture, data flow, lifecycle)
- Current state of the art — tooling, adoption, standards
- Key terminology and taxonomy

**Reference**: `references/viewpoint-direct-investigation.md`

### Viewpoint 2: Practitioner Perspective

**Core Question**: How do teams use this in production? What works?

**Focus Areas**:
- Real-world adoption patterns
- Common implementation approaches and trade-offs
- Practical gotchas documentation doesn't cover
- Operational concerns (debugging, monitoring, maintenance)
- Team skill requirements and learning curves

**Reference**: `references/viewpoint-practitioner.md`

### Viewpoint 3: Contrarian Angle

**Core Question**: What failure modes do most people overlook?

**Focus Areas**:
- Failure modes advocates rarely mention
- Scenarios where this is the wrong choice
- Hidden costs (complexity, maintenance burden, cognitive load)
- Alternatives that might be simpler
- When NOT to use this

**Reference**: `references/viewpoint-contrarian.md`

### Viewpoint 4: First Principles

**Core Question**: What core problem does this solve? Minimal viable version?

**Focus Areas**:
- Fundamental problem being addressed (stripped of buzzwords)
- Why existing approaches are insufficient
- Minimal set of capabilities for value
- Essential vs. deferrable
- Decomposition into independent sub-problems

**Reference**: `references/viewpoint-first-principles.md`

### Viewpoint 5: Prior Art / Historical

**Core Question**: What similar patterns exist? Lessons from predecessors?

**Focus Areas**:
- Historical predecessors and analogous patterns
- Evolution trajectories — what succeeded, what failed, why
- Hype vs. foundational patterns
- Lessons applicable to current topic

**Reference**: `references/viewpoint-prior-art.md`

---

## Token Budget Management

| Checkpoint | Threshold | Action |
|------------|-----------|--------|
| After constructing all prompts | >30% consumed | Warn user: "5 agents will consume significant context" |
| After reading 3 of 5 outputs | Running tally | If approaching 55%, checkpoint with user |
| After synthesis | Must be 65% | Immediate | Create handoff, do not start additional work |

If token budget is insufficient to complete all 5 agents + synthesis, inform the user and suggest splitting (e.g., "3 agents this session, 2 + synthesis next session").

---

## Error Handling

| Scenario | Action |
|----------|--------|
| Agent returns empty output | Re-spawn once. If still empty, document gap in synthesis. |
| Agent returns truncated output | Accept as-is, note in diagnostics. |
| Agent fails to spawn | Re-spawn once. If still fails, reduce to 4 agents, document. |
| Token budget exceeded mid-session | Stop spawning, synthesize from available outputs, note incomplete. |
| User-provided document unreadable | AskUserQuestion for alternative source. |

---

## Diagnostic Output (REQUIRED)

**MANDATORY**: You MUST write diagnostic output after every invocation. This is Stage 4 and cannot be skipped.

Write to: `$PROJECT_DIR/logs/diagnostics/research-{YYYYMMDD-HHMMSS}.yaml`

**Template**: Use `templates/diagnostic-output.yaml` for the schema. Fill in actual values from the session.

---

## Completion Checklist

**IMPORTANT**: Before returning to the user, verify ALL items are complete:

- [ ] Stage 1: Pre-flight complete (topic defined, directories created, skills loaded)
- [ ] Stage 1: AskUserQuestion used if topic was ambiguous
- [ ] Stage 2: All 5 viewpoint agents spawned in parallel
- [ ] Stage 2: All agent outputs written to `$PROJECT_DIR/logs/research/{topic-slug}/`
- [ ] Stage 3: ALL 5 outputs read before writing synthesis
- [ ] Stage 3: Synthesis written using `templates/synthesis-output.md`
- [ ] Stage 3: AskUserQuestion used for post-synthesis review
- [ ] Stage 3: Critical Evaluation Gate applied to all user responses (classified as Factual/Opinion/Speculative)
- [ ] Stage 3: Follow-up research spawned for Speculative responses (or user declined with caveat added)
- [ ] Stage 3: Synthesis written to `$PROJECT_DIR/artifacts/research/{topic-slug}/synthesis.md`
- [ ] Stage 4: Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`

**Do NOT return to user until all checkboxes can be marked complete.**

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ashaykubal](https://github.com/ashaykubal)
- **Source:** [ashaykubal/essential-agents-skills](https://github.com/ashaykubal/essential-agents-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.