owflow 0.2.0 → 0.4.2

package/dist/skills/research/SKILL.md

@@ -1,462 +1,249 @@
----
-name: research
-description: Orchestrates comprehensive research workflows from question definition through findings documentation. Handles technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based reporting. Supports standalone research tasks and embedded research phase in other workflows.
-user-invocable: true
----
-
-# Research Orchestrator
-
-Systematic research workflow from question definition to evidence-based documentation.
-
-## Initialization
-
-**BEFORE executing any phase, you MUST complete these steps:**
-
-### Step 1: Load Framework Patterns
-
-**Read the framework reference file NOW using the Read tool:**
-
-1. `../orchestrator-framework/references/orchestrator-patterns.md` - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
-
-### Step 2: Initialize Workflow
-
-1. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
-2. **Create Task Directory**: `.owflow/tasks/research/YYYY-MM-DD-task-name/`
-3. **Initialize State**: Create `orchestrator-state.yml` with research context
-   - **CRITICAL**: Use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`.
-
-**Output**:
-
-```
-🚀 Research Orchestrator Started
-
-Task: [research question]
-Directory: [task-path]
-
-Starting Phase 1: Initialize research...
-```
-
----
-
-## When to Use
-
-Use when:
-
-- Need comprehensive research on a topic
-- Exploring codebase patterns or architecture
-- Gathering requirements or best practices
-- Want systematic evidence-based answers
-- Research will feed into development workflows
-
-**DO NOT use for**: Development tasks, bug fixes, performance optimization.
-
----
-
-## Core Principles
-
-1. **Evidence-Based**: Every finding must have source citation
-2. **Systematic**: Follow structured methodology for consistent results
-3. **Multi-Source**: Gather from codebase, docs, config, external sources
-4. **Synthesized**: Cross-reference findings, identify patterns
-5. **Actionable**: Produce outputs that enable next steps
-
----
-
-## Local References
-
-| File                                     | When to Use | Purpose                                                                                        |
-| ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
-| `references/research-methodologies.md`   | Phase 1     | Research type classification, methodology selection, gathering strategies, analysis frameworks |
-| `references/brainstorming-techniques.md` | Phase 3     | Divergent/convergent thinking, interactive exploration, scope guardrails                       |
-| `references/design-techniques.md`        | Phase 5     | Decision documentation (MADR), ADR guidance, decision linking                                  |
-
----
-
-## Phase Configuration
-
-| Phase | content                                                | activeForm                              | Agent/Skill                                                                  |
-| ----- | ------------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------- |
-| 1     | "Research foundation (init, plan, gather, synthesize)" | "Executing research foundation"         | Direct + research-planner + information-gatherer (xN) + research-synthesizer |
-| 2     | "Evaluate brainstorming value"                         | "Evaluating brainstorming value"        | Direct                                                                       |
-| 3     | "Generate solution alternatives"                       | "Generating solution alternatives"      | solution-brainstormer                                                        |
-| 4     | "Evaluate brainstorming alternatives"                  | "Evaluating brainstorming alternatives" | Direct (interactive)                                                         |
-| 5     | "Design high-level architecture"                       | "Designing high-level architecture"     | Direct + solution-designer                                                   |
-| 6     | "Summarize research and suggest next steps"            | "Completing research"                   | Direct                                                                       |
-
----
-
-## Research Types
-
-| Type             | Keywords                                 | Focus                       | Typical Outputs                   |
-| ---------------- | ---------------------------------------- | --------------------------- | --------------------------------- |
-| **Technical**    | "how does", "where is", "implementation" | Codebase analysis           | Knowledge base, architecture docs |
-| **Requirements** | "what are requirements", "user needs"    | User/business needs         | Specifications, requirements doc  |
-| **Literature**   | "best practices", "industry standards"   | External research           | Recommendations, comparisons      |
-| **Mixed**        | Multiple keywords, broad questions       | Comprehensive investigation | All output types                  |
-
----
-
-## Workflow Phases
-
-### Phase 1: Research Foundation
-
-**Purpose**: Initialize research, plan methodology, gather information from all sources, and synthesize findings into a research report
-**Execute**: Multi-step: Direct + research-planner + information-gatherer (xN) + research-synthesizer
-**Output**: `planning/research-brief.md`, `planning/research-plan.md`, `planning/sources.md`, `analysis/findings/*.md`, `analysis/synthesis.md`, `outputs/research-report.md`
-**State**: Set `research_context.research_type`, `research_question`, `scope`, `methodology`, `sources`, `confidence_level`, `gathering_strategy`
-
-This phase executes 4 sequential steps. On resume, check existing artifacts to skip completed steps.
-
-#### Step 1: Initialize (Direct)
-
-**Artifacts**: `planning/research-brief.md`
-**Resume check**: If `planning/research-brief.md` exists, skip to Step 2
-
-1. Parse research question (from command or prompt user)
-2. Classify research type (auto-detect from keywords or use `--type` flag)
-3. Determine scope (included, excluded, constraints)
-4. Define success criteria
-5. Create research brief
-6. Update state: set `research_context.research_type`, `research_question`, `scope`
-7. **Discover project documentation**: Read `.owflow/docs/INDEX.md` (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as `research_context.project_doc_paths` in state.
-
-#### Step 2: Plan (Subagent)
-
-**Artifacts**: `planning/research-plan.md`, `planning/sources.md`
-**Resume check**: If `planning/research-plan.md` AND `planning/sources.md` exist, skip to Step 3
-
-**Read `references/research-methodologies.md` NOW using the Read tool** — research type classification, methodology selection, gathering strategies
-
-**INVOKE NOW**: Use Task tool with `subagent_type: research-planner`
-
-**Context to pass**: task_path, research_brief_path, research_type, research_question, scope, project_doc_paths (from state)
-
-Update state: `research_context.methodology`, `sources`
-
-#### Step 3: Gather + Merge (Parallel Subagents + Direct)
-
-**Artifacts**: `analysis/findings/*.md` (category-specific)
-**Resume check**: If any `analysis/findings/*.md` files exist, skip to Step 4
-
-**Determine gatherer count and categories**:
-
-1. Read `planning/research-plan.md` for **Gathering Strategy** section
-2. If gathering strategy found: use specified categories and count (cap at 8 max)
-3. If no gathering strategy: fall back to default 4 categories (codebase, documentation, configuration, external)
-4. Update state: `research_context.gathering_strategy`
-
-**CRITICAL: Launch all N agents in ONE message for parallel execution.**
-
-**Parallel Execution Pattern**:
-
-```
-Read gathering strategy from research-plan.md
-For each category in strategy:
-  Use Task tool: source_category=[category_id] → analysis/findings/[prefix]-*.md
-```
-
-#### Step 4: Synthesize (Subagent)
-
-**Artifacts**: `analysis/synthesis.md`, `outputs/research-report.md`
-**Resume check**: If `analysis/synthesis.md` AND `outputs/research-report.md` exist, skip (Phase 1 complete)
-
-**INVOKE NOW**: Use Task tool with `subagent_type: research-synthesizer`
-
-**Context to pass**: task_path, findings_directory_path, research_question, research_type, methodology
-
-**Synthesizer produces**:
-
-- Pattern analysis and cross-references (`analysis/synthesis.md`)
-- Comprehensive research report answering research question (`outputs/research-report.md`)
-- Confidence levels for each finding
-- Documented gaps and uncertainties
-
-Update state: `research_context.confidence_level`
-
----
-
-→ Pause
-
-question - "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?"
-
----
-
-### Phase 2: Optional Phases Decision
-
-> **Phase gate**: Requires `question` confirmation from Phase 1 before executing.
-
-**Purpose**: Evaluate whether brainstorming and/or design phases would be valuable (independently)
-**Execute**: Direct
-**Output**: Updated `orchestrator-state.yml`
-**State**: Set `options.brainstorming_enabled`, `options.design_enabled`
-
-**Auto-resolve if**: `--brainstorm`/`--no-brainstorm` flags (brainstorming only), `--design`/`--no-design` flags (design only)
-
-**Process**:
-
-1. Read `analysis/synthesis.md` summary and `research_type` from state
-2. Evaluate brainstorming value based on:
-   - Number of viable approaches identified in synthesis (multiple → valuable)
-   - Problem novelty (new domain → valuable; well-understood → less so)
-   - Whether synthesis identified competing trade-offs (yes → valuable)
-3. Evaluate design value based on:
-   - Whether research suggests architectural decisions (yes → valuable)
-   - Research type (requirements/mixed → likely valuable; technical → depends)
-   - Whether design artifacts would feed into development workflow
-4. If `brainstorming_enabled` not already set by flag, question:
-   - "[Brainstorming recommendation]. Would you like to explore solution alternatives?"
-   - Options: "Yes, explore alternatives" / "No, skip brainstorming"
-5. If `design_enabled` not already set by flag, question:
-   - "[Design recommendation]. Would you like to generate a high-level design?"
-   - Options: "Yes, generate design" / "No, skip design"
-6. Update state: set `brainstorming_enabled` and `design_enabled`
-
-→ If brainstorming enabled: continue to Phase 3
-→ If brainstorming disabled AND design enabled: skip to Phase 5
-→ If both disabled: skip to Phase 6
-
----
-
-### Phase 3: Solution Generation
-
-**Purpose**: Generate solution alternatives from research evidence using specialized brainstormer subagent
-**Execute**: solution-brainstormer subagent
-**Output**: `outputs/solution-exploration.md`
-**State**: Update `phase_summaries.phase-3`
-
-**Skip if**: `brainstorming_enabled = false` (user chose to skip in Phase 2, or `--no-brainstorm` flag)
-
-**Read `references/brainstorming-techniques.md` NOW using the Read tool** — divergent/convergent thinking techniques, scope guardrails
-
-> **ANTI-PATTERN**: Do NOT generate solution alternatives inline. The solution-brainstormer agent has specialized multi-perspective analysis capabilities.
-
-**INVOKE NOW**: Use Task tool with `subagent_type: solution-brainstormer`
-
-**Context to pass** (Pattern 7):
-
-- `task_path`, `synthesis_path`, `research_report_path`
-- `output_path`: `outputs/solution-exploration.md` — brainstormer MUST write to this exact path
-- Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries` (Phase 1)
-- `project_doc_paths` (from state)
-
-> **SELF-CHECK**: After Task tool returns, verify `outputs/solution-exploration.md` exists and contains alternatives. If missing: **STOP. Do NOT proceed to Phase 4 or Phase 5.** Re-invoke the brainstormer with corrected context (ensure `output_path` is `outputs/solution-exploration.md`). If second attempt also fails, use question to report the failure and ask whether to retry or skip brainstorming.
-
-→ **AUTO-CONTINUE**
-
----
-
-### Phase 4: Solution Convergence
-
-**Purpose**: Present brainstorming alternatives to user for decision-making on each decision area
-**Execute**: Direct (interactive)
-**Output**: Updated `orchestrator-state.yml` with chosen approaches
-**State**: Update `phase_summaries.phase-4` with `decision_areas` and `deferred_ideas`
-
-**Skip if**: `brainstorming_enabled = false`
-**Resume check**: If `phase_summaries.phase-4.decision_areas` has entries with `chosen_approach` set, skip already-resolved areas
-
-> **ANTI-PATTERN**: Do NOT present all decision areas in a single summary table and ask one combined "do you agree?" question. Each area MUST get its own detailed presentation and its own question call.
->
-> **ANTI-PATTERN**: Do NOT show full alternatives/pros/cons for the first area and then shortcut remaining areas to just a recommendation line + question. EVERY area gets the SAME level of detail — all alternatives with descriptions, pros, and cons. No exceptions.
-
-1. Read `outputs/solution-exploration.md`
-2. For each decision area sequentially, output ALL of the following (steps a-d) BEFORE calling question:
-   a. **Area header**: area name and why this decision matters (1-2 sentences of context)
-   b. **Alternatives detail**: For EVERY alternative in this area, show:
-   - Name and description (2-3 sentences)
-   - Pros (bullet list)
-   - Cons (bullet list)
-     c. **Recommendation**: which alternative is recommended and why (1 sentence)
-     d. **question**: this area's alternatives as options (mark recommended with "(Recommended)") + "Need more info" option
-     e. If user picks → record choice, move to next area
-     f. If "Need more info" → present the detailed trade-off analysis for the requested alternative, then re-ask
-
-> **SELF-CHECK before each question**: Did you output the alternatives with pros/cons for THIS area? If you only showed a recommendation line without listing all alternatives and their pros/cons, STOP and output the full detail before asking.
-
-3. After all areas resolved, present a brief summary of the chosen combination
-4. Update state with chosen approaches per decision area
-
-> **GATE CHECK**: Verify that question was called for EACH decision area. If any decision area was skipped for any reason (e.g., output file missing, read failure), STOP and resolve before continuing. Do NOT mark Phase 4 complete without user convergence on all decision areas.
-
-→ Pause
-
-question - "Brainstorming complete. Continue to high-level design?"
-
----
-
-### Phase 5: High-Level Design
-
-> **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
-
-**Purpose**: Create architecture design from selected solution approach
-**Execute**: Orchestrator-Direct Hybrid
-**Output**: `outputs/high-level-design.md`, `outputs/decision-log.md`
-**State**: Update `phase_summaries.phase-5`
-
-**Skip if**: `design_enabled = false`
-
-**Read `references/design-techniques.md` NOW using the Read tool** — MADR format, ADR guidance, decision documentation patterns
-
-**Part A — Design Direction (Direct)**:
-
-1. If Phase 4 ran: confirm selected approaches from convergence
-2. If Phase 4 was skipped: use research report recommendations as design input
-3. question for any design preferences or constraints (e.g., "Any architectural constraints or preferences?")
-
-**Part B — Design Generation (Subagent)**:
-
-> **ANTI-PATTERN**: Do NOT generate C4 architecture diagrams or ADRs inline. The solution-designer agent has specialized architecture and MADR documentation capabilities.
-
-**INVOKE NOW**: Use Task tool with `subagent_type: solution-designer`
-
-**Context to pass** (Pattern 7):
-
-- `task_path`, `synthesis_path`, `research_report_path`
-- `solution_exploration_path` (only if Phase 3-4 ran)
-- `selected_approach` (from Phase 4 convergence if ran, or from research report recommendations)
-- `design_preferences` (from Part A)
-- Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries`
-- `project_doc_paths` (from state)
-
-> **SELF-CHECK**: After Task tool returns, verify both `outputs/high-level-design.md` and `outputs/decision-log.md` exist. If missing: **STOP. Do NOT proceed to Part C.** Re-invoke the designer with corrected context. If second attempt also fails, use question to report the failure and ask whether to retry or skip design.
-
-**Part C — Summary (Direct)**: 3. Read `outputs/high-level-design.md` and `outputs/decision-log.md` 4. Present executive summary to user:
-
-- Architecture style and key components
-- Number of architectural decisions recorded
-- Key decision highlights (1 line each)
-- Integration points with existing system (if applicable)
-
-**Part D — Diagram Refinement (Skill, content-preserving)**:
-
-5. Invoke Skill tool: `diagrams-mermaid` to refine visual communication in `outputs/high-level-design.md`
-6. Add diagrams that supplement (not replace) existing architecture content:
-   - one architecture view (`C4Container` preferred, `C4Component` only if needed),
-   - one interaction/state view (`sequenceDiagram` or `flowchart`) for the critical flow.
-7. If minimum context for a diagram is missing, record explicit gaps in the document and avoid speculative components/relationships.
-
-→ Pause
-
-question - "Design complete. Continue to output generation?"
-
----
-
-### Phase 6: Completion
-
-> **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
-
-**Purpose**: Summarize research results and suggest next steps
-**Execute**: Direct
-**Output**: No new files — summarizes existing outputs
-
-**Process**:
-
-1. Inventory all generated outputs: `outputs/research-report.md` (always), plus conditional: `solution-exploration.md`, `high-level-design.md`, `decision-log.md`
-2. Present executive summary to user:
-   - Key findings and confidence level
-   - Which optional phases ran (brainstorming, design)
-   - Key decision highlights (if brainstorming/design ran)
-3. If design artifacts exist, suggest starting development in a fresh session:
-   ```
-   To start development based on this research, clear context first or start a new session, then run:
-   /development [task-path]
-   ```
-
-→ End of workflow
-
----
-
-## Domain Context (State Extensions)
-
-Research-specific fields in `orchestrator-state.yml`:
-
-Refer to the template [src/templates/orchestrator-state-research.yml](../../templates/orchestrator-state-research.yml).
-
----
-
-## Task Structure
-
-```
-.owflow/tasks/research/YYYY-MM-DD-research-name/
-├── orchestrator-state.yml
-├── planning/
-│   ├── research-brief.md           # Phase 1, Step 1
-│   ├── research-plan.md            # Phase 1, Step 2
-│   └── sources.md                  # Phase 1, Step 2
-├── analysis/
-│   ├── findings/
-│   │   ├── codebase-*.md           # Phase 1, Step 3
-│   │   ├── docs-*.md               # Phase 1, Step 3
-│   │   ├── config-*.md             # Phase 1, Step 3
-│   │   ├── external-*.md           # Phase 1, Step 3
-│   │   └── [custom-category]-*.md  # Phase 1, Step 3 (dynamic categories)
-│   └── synthesis.md                # Phase 1, Step 4 (reasoning log)
-├── outputs/
-│   ├── research-report.md          # Phase 1, Step 4 (main deliverable)
-│   ├── solution-exploration.md     # Phase 3 (conditional)
-│   ├── high-level-design.md        # Phase 5 (conditional)
-│   └── decision-log.md             # Phase 5 (conditional)
-```
-
----
-
-## Auto-Recovery
-
-| Phase      | Max Attempts | Strategy                                                      |
-| ---------- | ------------ | ------------------------------------------------------------- |
-| 1 (Step 1) | 1            | Prompt user for clarification if question unclear             |
-| 1 (Step 2) | 2            | Expand search patterns, use fallback mixed methodology        |
-| 1 (Step 3) | 3            | Retry failed agents only, continue with successful categories |
-| 1 (Step 4) | 2            | Request targeted re-gathering for gaps                        |
-| 2          | 1            | Re-evaluate recommendation if synthesis unclear               |
-| 3          | 2            | Re-invoke solution-brainstormer with adjusted context         |
-| 4          | 1            | Re-read exploration file, re-present decision areas           |
-| 5          | 2            | Re-invoke solution-designer with adjusted context             |
-| 6          | 0            | Summary only                                                  |
-
----
-
-## Integration with Other Workflows
-
-### As Standalone Research
-
-**Command**: `/research [research-question]`
-**Flow**: Complete all phases, save outputs in task directory
-
-### As Embedded Research Phase
-
-**Invoked by**: development orchestrator, migration orchestrator
-
-**Integration**:
-
-1. Parent orchestrator invokes research skill
-2. Research executes phases 1-5 (skip Phase 6 completion — parent orchestrator handles next steps)
-3. Design outputs fed into parent's specification phase
-4. Research report saved in parent task's `analysis/research/` directory
-
-**Handoff**:
-
-Refer to `research_outputs` in the template [src/templates/orchestrator-state-research.yml](../../templates/orchestrator-state-research.yml).
-
----
-
-## Command Integration
-
-Invoked via:
-
-- `/research [question] [--type=TYPE] [--brainstorm] [--no-brainstorm] [--design] [--no-design]` (new)
-- `/research [task-path] [--from=PHASE]` (resume)
-
-**Brainstorming flags**:
-
-- `--brainstorm`: Force brainstorming phase (auto-resolves Phase 2 brainstorming decision to "enable")
-- `--no-brainstorm`: Skip brainstorming phase
-- Neither: Phase 2 presents recommendation and asks user
-
-**Design flags**:
-
-- `--design`: Force high-level design phase (auto-resolves Phase 2 design decision to "enable")
-- `--no-design`: Skip high-level design phase
-- Neither: Phase 2 presents recommendation and asks user
-
-Task directory: `.owflow/tasks/research/YYYY-MM-DD-task-name/`
+---
+name: owflow:research
+description: Research workflow dispatcher. Initializes/resumes research tasks, derives the next step from state, and hands off to the matching /owflow:research-* subskill. Handles comprehensive research and analysis — technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based artifact outputs (findings documentation). Supports standalone research tasks and embedded research phases feeding development workflows. Use /owflow:goal-research to run all phases in one session.
+argument-hint: "[task description | task-path] [--from=<slug>] [--type=<type>]"
+user-invocable: true
+---
+
+# Research Dispatcher
+
+Entry point for research tasks in **assisted mode**: initialize (or resume) the task, derive the next pending step from `orchestrator-state.yml`, print the matching subskill command, and STOP. Each `/owflow:research-*` subskill runs its steps with fresh context — the explicit invocation IS the step gate.
+
+Research state uses descriptive step slugs in `completed_phases` / `failed_phases` / `auto_fix_attempts` (NOT phase numbers): `brief-written`, `plan-created`, `findings-gathered`, `synthesis-complete`, `alternatives-generated`, `approaches-chosen`, `design-generated`, `research-completed`. The routing table below maps slugs to subskills.
+
+For the all-in-one loop with in-session `question` gates, use `/owflow:goal-research`.
+
+Gates follow the shared contract in the [Gate Contract](../orchestrator-framework/references/gate-contract.md), with the [dispatcher exception](../orchestrator-framework/references/gate-contract.md).
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode                                                       | Quick mode                                                                                          |
+| ---------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Argument (question / path)                     | research question (new task) or task path/identifier (resume)       | task path/identifier only — quick runs are never STARTED here; an interrupted quick task resumes at full fidelity |
+| `orchestrator-state.yml`                       | read on resume (artifact validation of `completed_phases`)          | read on resume — honors `entry_point: "research-quick"` and quick-lane artifacts                            |
+| Task directory + `orchestrator-state.yml` init | written (Step 3, new task) — `entry_point: "research"`              | n/a — quick bootstrap is owned by `/owflow:research-quick`                                                  |
+
+The dispatcher writes nothing else — every task artifact is produced by the subskills (see [Task Structure](#task-structure)).
+
+## Entry Gate
+
+**BEFORE deriving the handoff, complete these steps:**
+
+### Step 1: Load Framework Patterns
+
+**Read the framework reference files NOW using the Read tool:**
+
+1. The [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) governs this skill.
+2. The [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) bound what subskills delegate.
+3. The [Orchestrator Patterns](../orchestrator-framework/references/orchestrator-patterns.md) define state schema, initialization, and context passing.
+
+### Step 2: Resolve the Argument
+
+**If the argument is a task path or identifier** (a directory, or a directory name under `.owflow/tasks/research/`) → **resume mode**:
+
+1. Read `orchestrator-state.yml`; validate expected artifacts for `completed_phases` (remove entries whose artifacts are missing)
+2. Find resume point: first step slug NOT in `completed_phases`; `--from=<slug>` overrides (validate its prerequisites exist, else use `question`)
+3. Missing state file → print: `No research task found at <path>. Run /owflow:research <question> to start from scratch.` and STOP
+
+**If the argument is a research question description** (any other free text) → new task.
+
+**If nothing is provided** → ask via `question`: "What is your research question?" (free-form answer), then WAIT. Never guess or auto-pick a task.
+
+### Step 3: Initialize (new task)
+
+**New task** (research question argument):
+
+1. **Create Task Directory**: `.owflow/tasks/research/YYYY-MM-DD-task-name/` (3-5 kebab-case words from the question)
+2. **Initialize State**: create `orchestrator-state.yml` from the research template — `task.title` / `task.description` from the question, `task.status: in_progress`, `orchestrator.task_path`, `orchestrator.entry_point: "research"` (template/bootstrap mechanic)
+   - **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`.
+3. **Create Task Items**: use `TaskCreate` for the research steps (one item per subskill handoff), then set the execution order with `TaskUpdate addBlockedBy` (plan → gather → synthesize → optional chain (user choice) → finalize). On resume, refresh the already-evidenced items instead of re-creating them.
+4. **Command flags**: `--type=TYPE` → `research_context.research_type`. Subskills read it from there.
+
+**Output**:
+
+```
+🚀 Research Dispatcher
+
+Task: [research question]
+Directory: [task-path]
+Next step: [step name]
+```
+
+---
+
+## When to Use
+
+Use when:
+
+- Need comprehensive research on a topic
+- Exploring codebase patterns or architecture
+- Gathering requirements or best practices
+- Want systematic evidence-based answers
+- Research will feed into development workflows
+
+**DO NOT use for**: Development tasks, bug fixes, performance optimization.
+
+---
+
+## Core Principles
+
+1. **Evidence-Based**: Every finding must have source citation
+2. **Systematic**: Follow structured methodology for consistent results
+3. **Multi-Source**: Gather from codebase, docs, config, external sources
+4. **Synthesized**: Cross-reference findings, identify patterns
+5. **Actionable**: Produce outputs that enable next steps
+
+---
+
+## Routing Table (completed_phases → next subskill)
+
+Derive the FIRST step slug not in `completed_phases`, then print the matching command:
+
+| Next step (slug)                                              | Condition (from state)                                                                                          | Handoff command                          | Produces                                                   |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| Brief + plan (`brief-written`, `plan-created`)                 | Always (new task or partial foundation)                                                                          | `/owflow:research-plan <task-path>`      | `planning/research-brief.md`, `research-plan.md`, `sources.md` |
+| Gather (`findings-gathered`)                                  | `plan-created` completed (gather parses `## Gathering Strategy`, or falls back to 4 default categories)           | `/owflow:research-gather <task-path>`    | `analysis/findings/*.md`                                    |
+| Synthesize (`synthesis-complete`)                             | `findings-gathered` completed                                                                                    | `/owflow:research-synthesize <task-path>` | `analysis/synthesis.md`, `outputs/research-report.md`       |
+| Optional chain (user choice)                                  | `synthesis-complete` completed — ask via `question` whether to brainstorm, design, or finalize; hand off to the chosen subskill | `/owflow:research-brainstorm` / `/owflow:research-design` / `/owflow:research-finalize <task-path>` | user's chain decision |
+| Brainstorm (`alternatives-generated`)                         | User chose brainstorming (invoking the skill IS the decision)                                                    | `/owflow:research-brainstorm <task-path>` | `outputs/solution-exploration.md`                           |
+| Converge (`approaches-chosen`)                                | `alternatives-generated` completed (brainstorm ran)                                                              | `/owflow:research-converge <task-path>`  | per-area `chosen_approach` in state (`phase_summaries.converge`) |
+| Design (`design-generated`)                                   | User chose design — after `approaches-chosen`, or as the design-only branch (seeded from the research report)     | `/owflow:research-design <task-path>`    | `outputs/high-level-design.md`, `outputs/decision-log.md`   |
+| Finalization (`research-completed`)                           | Foundation complete + optional chain settled (every step the user chose to run is recorded)                      | `/owflow:research-finalize <task-path>`  | task completed (`task.status: completed`)                   |
+
+The optional chain is the user's choice — there is no enablement flag in state and no separate decision step. When the user invokes `research-brainstorm` or `research-design`, that invocation IS the decision to run it; when they skip to `research-finalize`, the chain is settled as skipped. After `synthesis-complete` the dispatcher asks which way to go (brainstorm → converge → design, design-only, or straight to finalize).
+
+`research-completed` already in `completed_phases` → the task is TERMINAL: no handoff.
+
+This dispatcher never starts or forwards quick runs. An interrupted quick task (`entry_point: "research-quick"`, `synthesis-complete` not yet recorded) resumes at full fidelity for the missing pieces via the matching subskills. To finish that pass condensed, the user runs `/owflow:research-quick <task-path>` directly.
+
+Forking (utility, not a routing row): `/owflow:research-fork <task-path> ["<what this fork should explore>"] [--from=<slug>] [--name="..."]` copies a task with at least one completed step to a new task diverging at a chosen completed step — a bare path is enough, the skill asks for the intent, fork point, and name with suggestions drawn from that research; the directory is copied verbatim and the copied state is trimmed to continue from the fork point onwards; the source stays untouched. The fork is a plain research task from then on, routable by this dispatcher like any other.
+
+References moved into their owning subskills (read there, not here): `research-methodologies.md` lives in `research-plan/references/`, `brainstorming-techniques.md` in `research-brainstorm/references/`, `design-techniques.md` in `research-design/references/`.
+
+---
+
+## Exit Gate (adapted for dispatch mode)
+
+After deriving the handoff, present the results box, ask how to proceed, then hand off accordingly (see the [dispatcher exception](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the subskill.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH TASK READY — <task name>
+
+**Task** — [research question]
+**Directory** — `<task-path>`
+**Next step** — [step name]
+[Resume note: completed steps / fresh task]
+
+**Next ▸** `/owflow:research-<subskill> <task-path>`
+```
+
+### Acceptance question
+
+Use `question` — "Task ready. How would you like to proceed?" with options:
+
+- **Hand off to /owflow:research-<subskill>** — the user invokes the suggested command (dispatcher copies it to chat for convenience). Execution starts in a fresh context.
+- **Switch to autonomous mode** — illustrate with `/owflow:goal-research <task-path>` to run remaining steps in one session with gates.
+- **Adjust** — task set-up is wrong (wrong flags, wrong question, wrong task); re-run the affected initialization step, re-present the results box.
+- **Stop here** — print the resume command (`/owflow:research <task-path>`) and end.
+
+### Handoff message
+
+On Accept (hand off choice), print, then STOP:
+
+```
+✓ Research task ready at <task-path>
+
+Next step:
+  → /owflow:research-<subskill> <task-path>
+
+Other options:
+  /owflow:goal-research <task-path>   — run remaining steps in one loop
+  /owflow:research --from=<slug> <task-path>   — jump to a specific step
+```
+
+---
+
+## Task Structure
+
+```
+.owflow/tasks/research/YYYY-MM-DD-research-name/
+├── orchestrator-state.yml
+├── planning/
+│   ├── research-brief.md           # research-plan (brief step)
+│   ├── research-plan.md            # research-plan (plan step)
+│   └── sources.md                  # research-plan (plan step)
+├── analysis/
+│   ├── findings/
+│   │   ├── codebase-*.md           # research-gather (per category)
+│   │   ├── docs-*.md               # research-gather
+│   │   ├── config-*.md             # research-gather
+│   │   ├── external-*.md           # research-gather
+│   │   └── [custom-category]-*.md  # research-gather (dynamic categories)
+│   └── synthesis.md                # research-synthesize (reasoning log)
+├── outputs/
+│   ├── research-report.md          # research-synthesize (main deliverable)
+│   ├── solution-exploration.md     # research-brainstorm (conditional)
+│   ├── high-level-design.md        # research-design (conditional)
+│   └── decision-log.md             # research-design (conditional)
+```
+
+---
+
+## Research Types
+
+| Type             | Keywords                                 | Focus                       | Typical Outputs                   |
+| ---------------- | ---------------------------------------- | --------------------------- | --------------------------------- |
+| **Technical**    | "how does", "where is", "implementation" | Codebase analysis           | Knowledge base, architecture docs |
+| **Requirements** | "what are requirements", "user needs"    | User/business needs         | Specifications, requirements doc  |
+| **Literature**   | "best practices", "industry standards"   | External research           | Recommendations, comparisons      |
+| **Mixed**        | Multiple keywords, broad questions       | Comprehensive investigation | All output types                  |
+
+---
+
+## Integration with Other Workflows
+
+### As Standalone Research
+
+**Command**: `/owflow:research [research-question | task-path]` — the dispatcher hands off step by step; `/owflow:goal-research <task-path>` runs the complete workflow in one session with interactive gates.
+
+### As Embedded Research Phase (documentation only — no wiring)
+
+> This is documentation for parent-orchestrator authors, NOT an execution path of this dispatcher: nothing here auto-invokes a parent, and no research subskill chains into development or migration steps.
+
+In the split family, a parent orchestrator (development, migration) that needs research sequences the research subskills directly via the Skill tool — plan → gather → synthesize → the optional chain as chosen by the user — and SKIPS `research-finalize`-style completion: the parent handles next steps and keeps control of the flow. Design artifacts feed the parent's specification phase; the research report is saved in the parent task's `analysis/research/` context per the parent's own state setup.
+
+**Handoff fields the parent reads**: refer to `research_outputs.*` in the template [src/templates/orchestrator-state-research.yml](../../templates/orchestrator-state-research.yml).
+
+Full autonomous research (research as its own goal, every gate honored) = `/owflow:goal-research`. A `--no-exit` flag for embedded runs is deferred — not part of this design.
+
+---
+
+## Auto-Recovery
+
+Retries are owned by each subskill (each `/owflow:research-*` SKILL.md carries its own max attempts and strategy).
+
+---
+
+## Command Flags
+
+| Flag                              | Effect                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------ |
+| `--from=<slug>`                   | Hand off (resume mode) from a specific step slug                                     |
+| `--type=<type>`                   | Force the research type classification ("technical \| requirements \| literature \| mixed") |
+
+There is deliberately NO quick entry on this dispatcher — condensed quick starts go through `/owflow:research-quick`, whose artifacts this routing table honors on every row.
+
+---
+
+## Command Integration
+
+Invoked via:
+
+- `/owflow:research [question] [--type=TYPE]` (new)
+- `/owflow:research [task-path] [--from=<slug>]` (resume)
+
+Alternative: `/owflow:goal-research <task-path>` — same task lifecycle, all subskills invoked in one session with `question` gates.
+
+Task directory: `.owflow/tasks/research/YYYY-MM-DD-task-name/`