missions/.cursor/skills/research/SKILL.md

---
name: research
description: |
  Deep Research Methodology (8-Step Method) with two execution modes:
  - Mode A (Initial Research): Assess acceptance criteria, then research problem and produce solution draft
  - Mode B (Solution Assessment): Assess existing solution draft for weak points and produce revised draft
  Supports project mode (_docs/ structure) and standalone mode (@file.md).
  Auto-detects research mode based on existing solution_draft files.
  Trigger phrases:
  - "research", "deep research", "deep dive", "in-depth analysis"
  - "research this", "investigate", "look into"
  - "assess solution", "review solution draft"
  - "comparative analysis", "concept comparison", "technical comparison"
category: build
tags: [research, analysis, solution-design, comparison, decision-support]
disable-model-invocation: true
---

# Deep Research (8-Step Method)

Transform vague topics raised by users into high-quality, deliverable research reports through a systematic methodology. Operates in two modes: **Initial Research** (produce new solution draft) and **Solution Assessment** (assess and revise existing draft).

## Core Principles

- **Conclusions come from mechanism comparison, not "gut feelings"**
- **Pin down the facts first, then reason**
- **Prioritize authoritative sources: L1 > L2 > L3 > L4**
- **Intermediate results must be saved for traceability and reuse**
- **Ask, don't assume** — when any aspect of the problem, criteria, or restrictions is unclear, STOP and ask the user before proceeding
- **Internet-first investigation** — do not rely on training data for factual claims; search the web extensively for every sub-question, rephrase queries when results are thin, and keep searching until you have converging evidence from multiple independent sources
- **Multi-perspective analysis** — examine every problem from at least 3 different viewpoints (e.g., end-user, implementer, business decision-maker, contrarian, domain expert, field practitioner); each perspective should generate its own search queries
- **Question multiplication** — for each sub-question, generate multiple reformulated search queries (synonyms, related terms, negations, "what can go wrong" variants, practitioner-focused variants) to maximize coverage and uncover blind spots
- **Component option breadth** — for every component area, build a broad option landscape before selecting. Search direct candidates, adjacent-domain alternatives, commercial/open-source variants, classical/simple baselines, current SOTA, and "do not use" failure cases. A component may not be narrowed to one candidate until alternatives have been searched and rejected with evidence.
- **Component research depth** — for every serious component candidate, go beyond discovery pages. Read official docs, repository/license files, issue discussions, benchmarks, deployment guides, version/platform requirements, security notes, maintenance signals, and real-world failure reports. Extract evidence for inputs/outputs, lifecycle assumptions, runtime/storage/latency fit, integration boundaries, licensing, operational risks, and unsupported scenarios before assigning any selection status.
- **Exact-fit component selection** — never select a component, tool, library, service, architecture pattern, or algorithm merely because it solves a similar class of problem. It must be proven compatible with the project's explicit operating context, constraints, required inputs/outputs, non-functional requirements, lifecycle assumptions, and acceptance criteria. If fit is unproven or mismatched, mark it `Rejected`, `Experimental only`, or escalate for user decision before it can shape the solution.
- **Per-mode API capability verification** *(applies only to technical-component selection — see Research Output Class below)* — when a candidate library/SDK/framework/service exposes multiple modes or configurations, *the candidate is not a single thing*. Pin the exact mode the project will use (one explicit sentence: inputs, outputs, runtime), and verify *that mode* against the project's required inputs/outputs via official docs (mandatory `context7` lookup) plus a saved Minimum Viable Example. Capability claims at the category level ("supports X, Y, Z modes") must be cross-checked against the literal mode enumeration before being treated as project-applicable. Two modes of one library are two distinct candidates for the purposes of the Component Applicability Gate. Does not apply to non-technical research (concept comparison, market/policy investigation, knowledge organization, etc.).

## Research Output Class (BLOCKING — set in Step 1)

Before applying any of the technical-component gates (per-mode API capability verification, Component Applicability Gate, Restrictions × Candidate-Mode sub-matrix, MVE evidence, mandatory `context7` lookup), classify the research output into one of two classes. Record the decision in `00_question_decomposition.md` once, near the top, so every downstream step honors it.

| Class | What the output recommends or selects | Examples | Technical-component gates apply? |
|-------|---------------------------------------|----------|----------------------------------|
| **Technical-component selection** | One or more libraries, SDKs, frameworks, services, protocols, data formats, infrastructure patterns, algorithms, or APIs that will be implemented or operated against | "Pick a vector database", "Compare auth-token strategies for our API", "Should we use Kafka or RabbitMQ?", architecture / tech-stack / migration drafts (Mode A, Mode B) | **Yes — all gates active** |
| **Non-technical investigation** | Concept comparisons, knowledge organization, root-cause investigation of an event, market/policy/regulatory/social analysis, literature review, decision support without committing to specific tooling | "Why did adoption stall in Q3?", "Compare phenomenology vs constructivism", "Map regulatory landscape for X", "What do practitioners say about onboarding under remote-first orgs?" | **No — skip API/MVE/sub-matrix gates; the rest of the 8-step engine still applies** |

How to decide:
1. Inspect the question and the input files (`problem.md`, `restrictions.md`, `acceptance_criteria.md`, or the standalone input file).
2. If the deliverable will name specific software/services/protocols that someone will then build with or operate, it is **Technical-component selection**.
3. If the deliverable is a report, comparison, or recommendation that does not commit to specific tooling, it is **Non-technical investigation**.
4. **Mixed runs are valid.** Some research questions have a non-technical core but include one technical sub-question (or vice versa). In that case classify per component area within the run, not the run as a whole, and note in `00_question_decomposition.md` which component areas trigger the technical-component gates.

When the run is purely **Non-technical investigation**, the rest of the research engine — question decomposition, perspective rotation, exhaustive web search, fact extraction, comparison framework, reasoning chain, validation, deliverable formatting — still applies in full. The sections that get skipped are explicitly the technical gates listed in the table above.

## Context Resolution

Determine the operating mode based on invocation before any other logic runs.

**Project mode** (no explicit input file provided):
- INPUT_DIR: `_docs/00_problem/`
- OUTPUT_DIR: `_docs/01_solution/`
- RESEARCH_DIR: `_docs/00_research/`
- All existing guardrails, mode detection, and draft numbering apply as-is.

**Standalone mode** (explicit input file provided, e.g. `/research @some_doc.md`):
- INPUT_FILE: the provided file (treated as problem description)
- BASE_DIR: if specified by the caller, use it; otherwise default to `_standalone/`
- OUTPUT_DIR: `BASE_DIR/01_solution/`
- RESEARCH_DIR: `BASE_DIR/00_research/`
- Guardrails relaxed: only INPUT_FILE must exist and be non-empty
- `restrictions.md` and `acceptance_criteria.md` are optional — warn if absent, proceed if user confirms
- Mode detection uses OUTPUT_DIR for `solution_draft*.md` scanning
- Draft numbering works the same, scoped to OUTPUT_DIR
- **Final step**: after all research is complete, move INPUT_FILE into BASE_DIR

Announce the detected mode and resolved paths to the user before proceeding.

## Project Integration

Read and follow `steps/00_project-integration.md` for prerequisite guardrails, mode detection, draft numbering, working directory setup, save timing, and output file inventory.

## Execution Flow

### Mode A: Initial Research

Read and follow `steps/01_mode-a-initial-research.md`.

Phases: AC Assessment (BLOCKING) → Problem Research → Tech Stack (optional) → Security (optional).

---

### Mode B: Solution Assessment

Read and follow `steps/02_mode-b-solution-assessment.md`.

---

## Research Engine (8-Step Method)

The 8-step method is the core research engine used by both modes. Steps 0-1 and Step 8 have mode-specific behavior; Steps 2-7 are identical regardless of mode.

**Investigation phase** (Steps 0–3.5): Read and follow `steps/03_engine-investigation.md`.
Covers: question classification, novelty sensitivity, question decomposition, perspective rotation, exhaustive web search, fact extraction, iterative deepening.

**Analysis phase** (Steps 4–8): Read and follow `steps/04_engine-analysis.md`.
Covers: comparison framework, baseline alignment, reasoning chain, use-case validation, deliverable formatting.

## Solution Draft Output Templates

- Mode A: `templates/solution_draft_mode_a.md`
- Mode B: `templates/solution_draft_mode_b.md`

## Escalation Rules

| Situation | Action |
|-----------|--------|
| Unclear problem boundaries | **ASK user** |
| Ambiguous acceptance criteria values | **ASK user** |
| Missing context files (`security_approach.md`, `input_data/`) | **ASK user** what they have |
| Conflicting restrictions | **ASK user** which takes priority |
| Technology choice with multiple valid options | **ASK user** |
| Contradictions between input files | **ASK user** |
| Missing acceptance criteria or restrictions files | **WARN user**, ask whether to proceed |
| File naming within research artifacts | PROCEED |
| Source tier classification | PROCEED |

## Trigger Conditions

When the user wants to:
- Deeply understand a concept/technology/phenomenon
- Compare similarities and differences between two or more things
- Gather information and evidence for a decision
- Assess or improve an existing solution draft

**Differentiation from other Skills**:
- Needs **research + solution draft** → use this Skill

## Stakeholder Perspectives

Adjust content depth based on audience:

| Audience | Focus | Detail Level |
|----------|-------|--------------|
| **Decision-makers** | Conclusions, risks, recommendations | Concise, emphasize actionability |
| **Implementers** | Specific mechanisms, how-to | Detailed, emphasize how to do it |
| **Technical experts** | Details, boundary conditions, limitations | In-depth, emphasize accuracy |

## Source Verifiability Requirements

Every cited piece of external information must be directly verifiable by the user. All links must be publicly accessible (annotate `[login required]` if not), citations must include exact section/page/timestamp, and unverifiable information must be annotated `[limited source]`. Full checklist in `references/quality-checklists.md`.

## Quality Checklist

Before completing the solution draft, run through the checklists in `references/quality-checklists.md`. This covers:
- General quality (L1/L2 support, verifiability, actionability)
- Mode A specific (AC assessment, competitor analysis, component tables, tech stack)
- Mode B specific (findings table, self-contained draft, performance column)
- Timeliness check for high-sensitivity domains (version annotations, cross-validation, community mining)
- Target audience consistency (boundary definition, source matching, fact card audience)

## Final Reply Guidelines

When replying to the user after research is complete:

**Should include**:
- Active mode used (A or B) and which optional phases were executed
- One-sentence core conclusion
- Key findings summary (3-5 points)
- Path to the solution draft: `OUTPUT_DIR/solution_draft##.md`
- Paths to optional artifacts if produced: `tech_stack.md`, `security_analysis.md`
- If there are significant uncertainties, annotate points requiring further verification

**Must not include**:
- Process file listings (e.g., `00_question_decomposition.md`, `01_source_registry.md`, etc.)
- Detailed research step descriptions
- Working directory structure display

**Reason**: Process files are for retrospective review, not for the user. The user cares about conclusions, not the process.