ashaykubal/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 <topic-or-prompt> [--context <file>]
/research --doc <path-to-document>

Arguments:

• <topic-or-prompt> - Free-text topic description or problem statement
• --context <file> - Additional context file to provide to all agents
• --doc <path> - 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 <65% after synthesis)

Enforcement: Do NOT begin writing synthesis until ALL available agent outputs have been read. The orchestrator must reference every agent's output at least once in the synthesis.

Critical Evaluation Gate (Post-User Q&A)

After each AskUserQuestion round, do NOT blindly incorporate user responses. Instead:

Step 1 — Classify each user response:

| Classification | Definition | Action | |---------------|------------|--------| | Factual | Known, verifiable information (e.g., "We use PostgreSQL") | Incorporate directly into synthesis | | Opinion | Preference or priority (e.g., "I'd prefer approach A") | Incorporate directly with attribution: "User preference: ..." | | Speculative | Unvalidated claim or proposed solution (e.g., "I think library X can do this", "What if we used approach Y?") | Do NOT incorporate. Trigger Step 2. |

Step 2 — For Speculative responses, present to user:

"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% | Leave room for session closing | | Synthesis complete at >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.