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