owflow 0.4.2 → 0.5.0

package/dist/skills/research-design/SKILL.md

@@ -1,146 +1,146 @@
----
-name: owflow:research-design
-description: Research skill — optional subskill. Asks design preferences (Part A), delegates high-level architecture design to the solution-designer agent (outputs/high-level-design.md + outputs/decision-log.md), then refines diagrams via the diagrams-mermaid Skill — content-preserving (design-generated). Invoking this skill IS the decision to design — there is no enablement flag.
-argument-hint: "[task-path-or-identifier]"
-user-invocable: true
----
-
-# Research Design — High-Level Design (design-generated)
-
-Work phase of the research workflow. Creates the high-level architecture design from the selected solution approach — or, when brainstorming did not run, seeded from the research-report recommendations — as two artifacts (`outputs/high-level-design.md`, `outputs/decision-log.md`), then refines diagrams via the `diagrams-mermaid` Skill. Optional phase — runs when the user chooses it: invoking this skill IS the decision to design (no enablement flag in state). The design-only branch (brainstorming not run) is owned here: `selected_approach` is seeded from the research report. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
-
-Related phases: `/owflow:research-brainstorm` + `/owflow:research-converge` (produce the chosen combination consumed as `selected_approach`), `/owflow:research-finalize` (always next). The design-techniques reference lives in this skill's own folder (`references/design-techniques.md`).
-
-## Entry Gate
-
-Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
-
-- **Path** (absolute or project-relative) to the task directory — use as-is.
-- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
-- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
-  1. Steps that must be completed first (in order), each with its command:
-     - Research brief & plan (`brief-written`, `plan-created`) → `/owflow:research-plan <task-path>`
-     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
-     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
-     - Chosen approaches (`approaches-chosen`) → `/owflow:research-brainstorm <task-path>` + `/owflow:research-converge <task-path>` (only when brainstorming ran)
-  2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
-  3. Hint: `Run /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
-
-### Prerequisites
-
-| Required for this skill | Where verified                                                                                                                             | Produced by                                                        |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| State file exists       | `<task-path>/orchestrator-state.yml`                                                                                                        | `/owflow:research <question>` or `/owflow:research-quick` |
-| Design input ready      | brainstorm ran — `approaches-chosen` in `completed_phases`; OR brainstorm did not run — `outputs/research-report.md` exists with recommendations | `/owflow:research-converge <task-path>` (or `/owflow:research-synthesize <task-path>`) |
-
-1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `design-generated`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch.` and STOP.
-2. **Prerequisite check**: `synthesis-complete` must be in `completed_phases`. If missing → print the blocked block (`→ /owflow:research-synthesize <task-path>`, or the earliest missing earlier step), then STOP.
-3. **Design input (branch resolution)**:
-   - `approaches-chosen` in `completed_phases` → brainstorm ran; the chosen combination from `phase_summaries.converge.decision_areas` is `selected_approach`.
-   - `approaches-chosen` in `completed_phases` but `phase_summaries.converge.decision_areas` has no `chosen_approach` → convergence never resolved its areas: `→ /owflow:research-converge <task-path>`, then STOP.
-   - `alternatives-generated` in `completed_phases` but `approaches-chosen` absent → the brainstorm chain is incomplete: `→ /owflow:research-converge <task-path>`, then STOP. Do NOT seed from the research report while alternatives exist.
-   - Neither slug present → brainstorming has not produced alternatives. Ask via `question`: "Brainstorming hasn't run — seed the design from the research report, or brainstorm first?" → seed from report (design-only branch): state `Brainstorming did not run — seeding the design from research-report recommendations.`, validate `outputs/research-report.md` exists (missing → `→ /owflow:research-synthesize <task-path>`, then STOP) and proceed; → brainstorm first: `→ /owflow:research-brainstorm <task-path>`, then STOP.
-4. **Skip/resume**: if `design-generated` is in `completed_phases`, validate BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md` exist; either missing → re-run Parts B-D below; both present → report the existing design summary and route to the Exit Gate.
-
-## Input / Output Artifacts
-
-| Artifact                                       | Normal mode (full lane)                                                   | Quick mode (`research-quick`)                                                                        |
-| ---------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| Consumed: `phase_summaries.converge.decision_areas` (chosen combination) | becomes `selected_approach` when brainstorm ran                       | same fields — when the optional chain runs after a quick pass, converge ran as the normal subskill        |
-| Consumed: `outputs/research-report.md`         | design-only branch seed (`selected_approach` from recommendations)           | identical — research-quick produces the same report artifact                                              |
-| Produced: `outputs/high-level-design.md`, `outputs/decision-log.md` | delegated to `solution-designer`, refined via `diagrams-mermaid` Skill | NOT produced in the quick pass — design always runs as this skill after the quick lane                    |
-| State write                                    | `design-generated`; `phase_summaries.design {summary, architecture_style, decisions_count}`, `research_outputs.high_level_design` + `.decision_log` | same (this skill never runs inside a quick pass)               |
-
-## Execute (Part A direct + Part B delegated + Part C direct + Part D Skill)
-
-**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
-
-**Read `references/design-techniques.md` NOW using the Read tool** — MADR format, ADR guidance, decision documentation patterns (own-folder reference).
-
-### Part A — Design Direction (direct)
-
-1. Brainstorm ran: read the chosen combination from `phase_summaries.converge.decision_areas` — it becomes `selected_approach`.
-2. Brainstorm did not run (design-only branch, resolved in Entry Gate step 3): read `outputs/research-report.md` recommendations and derive `selected_approach` from them; note the provenance (research-report recommendations, not convergence).
-3. `question` — "Any architectural constraints or preferences?" (free-form answer; empty means none). These `design_preferences` ride in the Part B context pass and are kept human-readable in `phase_summaries.design.summary` — the state template has NO dedicated `design_preferences` slot; that omission is deliberate (do NOT invent a template field).
-
-### Part B — Design Generation (subagent)
-
-> **ANTI-PATTERN — do NOT generate C4 architecture diagrams or ADRs inline. "The approach is obvious" is NOT a reason to skip delegation. The solution-designer agent has specialized architecture and MADR documentation capabilities.**
-
-1. **INVOKE NOW**: Task tool - `solution-designer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context):
-   - `task_path`, `synthesis_path` (`analysis/synthesis.md`), `research_report_path` (`outputs/research-report.md`)
-   - `solution_exploration_path` (`outputs/solution-exploration.md`) — only when brainstorm ran
-   - `selected_approach` (from convergence; on the no-brainstorm branch, seeded from research-report recommendations — list the provenance in the prompt)
-   - `design_preferences` (from Part A; omit when the user gave none)
-   - Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries`
-   - `project_doc_paths` (from state)
-   - MUST-contract: the designer writes BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md`
-2. > **SELF-CHECK**: After the Task tool returns, verify BOTH `outputs/high-level-design.md` and `outputs/decision-log.md` exist. If either is missing: **STOP. Do NOT proceed to Part D or the Exit Gate.** Re-invoke the designer with corrected context. If a second attempt also fails, use `question` to report the failure and ask whether to retry or skip design.
-
-### Part C — Executive Summary (direct)
-
-Read `outputs/high-level-design.md` and `outputs/decision-log.md`, then present the executive summary through the Exit-Gate results box below (architecture style and key components, decision count, key decision highlights 1 line each, integration points with the existing system if applicable) — no separate presentation round.
-
-### Part D — Diagram Refinement (Skill, content-preserving)
-
-1. **INVOKE NOW**: Skill tool - `diagrams-mermaid` to refine visual communication in `outputs/high-level-design.md`.
-2. 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.
-3. If minimum context for a diagram is missing, record explicit gaps in the document and avoid speculative components/relationships.
-
-### Close (`design-generated`)
-
-1. **State write**: append `design-generated` to `completed_phases` after the SELF-CHECK passes and Part D completes; update `research_context.phase_summaries.design {summary, architecture_style, decisions_count}` (keep the Part A preferences visible in `summary`); set `research_outputs.high_level_design` AND `research_outputs.decision_log`; bump `orchestrator.updated`. On failure: append `design-generated` to `failed_phases`, increment `auto_fix_attempts["design-generated"]`. Then re-read state + run `verify_template` (see State Update Convention).
-
-## State Update Convention (per step)
-
-Apply after EVERY step above:
-
-1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`design-generated`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
-2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
-3. **Failures** — if the designer delegation fails or its retries are abandoned, do NOT append `design-generated` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["design-generated"]`. A user-chosen skip via `question` after repeated failures is a deliberate decision, not a failure: record the reason in `phase_summaries.design.summary` and append neither `design-generated` nor a `failed_phases` entry. Then present the Exit Gate (results box notes the skip; next step is `/owflow:research-finalize <task-path>`).
-4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
-5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
-
-## Recovery
-
-| Step                          | Max Attempts | Strategy                                       |
-| ----------------------------- | ------------ | ----------------------------------------------- |
-| Design (`design-generated`)   | 2            | Re-invoke solution-designer with adjusted context |
-
-## Exit Gate
-
-Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. A user-chosen skip still uses this Exit Gate; its results box says the step was skipped and why, and the next step is `/owflow:research-finalize <task-path>`.
-
-### Results box
-
-```markdown
-## ✅ RESEARCH DESIGN COMPLETE — <research question>
-
-**Architecture style** — [style and key components]
-**Decisions recorded** — [N architectural decisions in decision-log.md]
-**Key highlights** — [1 line per key decision]
-**Integration points** — [with the existing system, if applicable]
-**Diagrams** — [refined by diagrams-mermaid / gaps recorded]
-
-**Artifacts**
-
-- `outputs/high-level-design.md`
-- `outputs/decision-log.md`
-```
-
-### Results-acceptance question
-
-Use `question` — "Are these results correct?" with options:
-
-- **Accept** — the architecture and decision log are good; continue.
-- **Adjust** — re-invoke the designer with the user's corrections (changed constraints or preferences), update state and artifacts, re-present the results box.
-- **Discuss** — walk through the architecture style or specific architectural decisions in more depth; then re-ask.
-- **Stop here** — print the resume command (`/owflow:research-design <task-path>`) and end.
-
-### Next steps (after Accept)
-
-- `→ /owflow:research-finalize <task-path>` — `required` next: inventories all research outputs (including these design artifacts) and completes the task (`research-completed`). Remaining after: none — development starts from finalize's handoff (`→ /owflow:development <task-path>`).
-
-Then STOP.
+---
+name: owflow:research-design
+description: Research skill — optional subskill. Asks design preferences (Part A), delegates high-level architecture design to the solution-designer agent (outputs/high-level-design.md + outputs/decision-log.md), then refines diagrams via the diagrams-mermaid Skill — content-preserving (design-generated). Invoking this skill IS the decision to design — there is no enablement flag.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Design — High-Level Design (design-generated)
+
+Work phase of the research workflow. Creates the high-level architecture design from the selected solution approach — or, when brainstorming did not run, seeded from the research-report recommendations — as two artifacts (`outputs/high-level-design.md`, `outputs/decision-log.md`), then refines diagrams via the `diagrams-mermaid` Skill. Optional phase — runs when the user chooses it: invoking this skill IS the decision to design (no enablement flag in state). The design-only branch (brainstorming not run) is owned here: `selected_approach` is seeded from the research report. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-brainstorm` + `/owflow:research-converge` (produce the chosen combination consumed as `selected_approach`), `/owflow:research-finalize` (always next). The design-techniques reference lives in this skill's own folder (`references/design-techniques.md`).
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+  1. Steps that must be completed first (in order), each with its command:
+     - Research brief & plan (`brief-written`, `plan-created`) → `/owflow:research-plan <task-path>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+     - Chosen approaches (`approaches-chosen`) → `/owflow:research-brainstorm <task-path>` + `/owflow:research-converge <task-path>` (only when brainstorming ran)
+  2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
+  3. Hint: `Run /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                                                                                                                             | Produced by                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                                                                                        | `/owflow:research <question>` or `/owflow:research-quick` |
+| Design input ready      | brainstorm ran — `approaches-chosen` in `completed_phases`; OR brainstorm did not run — `outputs/research-report.md` exists with recommendations | `/owflow:research-converge <task-path>` (or `/owflow:research-synthesize <task-path>`) |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `design-generated`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch.` and STOP.
+2. **Prerequisite check**: `synthesis-complete` must be in `completed_phases`. If missing → print the blocked block (`→ /owflow:research-synthesize <task-path>`, or the earliest missing earlier step), then STOP.
+3. **Design input (branch resolution)**:
+   - `approaches-chosen` in `completed_phases` → brainstorm ran; the chosen combination from `phase_summaries.converge.decision_areas` is `selected_approach`.
+   - `approaches-chosen` in `completed_phases` but `phase_summaries.converge.decision_areas` has no `chosen_approach` → convergence never resolved its areas: `→ /owflow:research-converge <task-path>`, then STOP.
+   - `alternatives-generated` in `completed_phases` but `approaches-chosen` absent → the brainstorm chain is incomplete: `→ /owflow:research-converge <task-path>`, then STOP. Do NOT seed from the research report while alternatives exist.
+   - Neither slug present → brainstorming has not produced alternatives. Ask via `question`: "Brainstorming hasn't run — seed the design from the research report, or brainstorm first?" → seed from report (design-only branch): state `Brainstorming did not run — seeding the design from research-report recommendations.`, validate `outputs/research-report.md` exists (missing → `→ /owflow:research-synthesize <task-path>`, then STOP) and proceed; → brainstorm first: `→ /owflow:research-brainstorm <task-path>`, then STOP.
+4. **Skip/resume**: if `design-generated` is in `completed_phases`, validate BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md` exist; either missing → re-run Parts B-D below; both present → report the existing design summary and route to the Exit Gate.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                   | Quick mode (`research-quick`)                                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Consumed: `phase_summaries.converge.decision_areas` (chosen combination) | becomes `selected_approach` when brainstorm ran                       | same fields — when the optional chain runs after a quick pass, converge ran as the normal subskill        |
+| Consumed: `outputs/research-report.md`         | design-only branch seed (`selected_approach` from recommendations)           | identical — research-quick produces the same report artifact                                              |
+| Produced: `outputs/high-level-design.md`, `outputs/decision-log.md` | delegated to `solution-designer`, refined via `diagrams-mermaid` Skill | NOT produced in the quick pass — design always runs as this skill after the quick lane                    |
+| State write                                    | `design-generated`; `phase_summaries.design {summary, architecture_style, decisions_count}`, `research_outputs.high_level_design` + `.decision_log` | same (this skill never runs inside a quick pass)               |
+
+## Execute (Part A direct + Part B delegated + Part C direct + Part D Skill)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md).
+
+**Read `references/design-techniques.md` NOW using the Read tool** — MADR format, ADR guidance, decision documentation patterns (own-folder reference).
+
+### Part A — Design Direction (direct)
+
+1. Brainstorm ran: read the chosen combination from `phase_summaries.converge.decision_areas` — it becomes `selected_approach`.
+2. Brainstorm did not run (design-only branch, resolved in Entry Gate step 3): read `outputs/research-report.md` recommendations and derive `selected_approach` from them; note the provenance (research-report recommendations, not convergence).
+3. `question` — "Any architectural constraints or preferences?" (free-form answer; empty means none). These `design_preferences` ride in the Part B context pass and are kept human-readable in `phase_summaries.design.summary` — the state template has NO dedicated `design_preferences` slot; that omission is deliberate (do NOT invent a template field).
+
+### Part B — Design Generation (subagent)
+
+> **ANTI-PATTERN — do NOT generate C4 architecture diagrams or ADRs inline. "The approach is obvious" is NOT a reason to skip delegation. The solution-designer agent has specialized architecture and MADR documentation capabilities.**
+
+1. **INVOKE NOW**: Task tool - `solution-designer` subagent (never the Skill tool — this is an agent). Pass (Pattern 7 — accumulated context):
+   - `task_path`, `synthesis_path` (`analysis/synthesis.md`), `research_report_path` (`outputs/research-report.md`)
+   - `solution_exploration_path` (`outputs/solution-exploration.md`) — only when brainstorm ran
+   - `selected_approach` (from convergence; on the no-brainstorm branch, seeded from research-report recommendations — list the provenance in the prompt)
+   - `design_preferences` (from Part A; omit when the user gave none)
+   - Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries`
+   - `project_doc_paths` (from state)
+   - MUST-contract: the designer writes BOTH `outputs/high-level-design.md` AND `outputs/decision-log.md`
+2. > **SELF-CHECK**: After the Task tool returns, verify BOTH `outputs/high-level-design.md` and `outputs/decision-log.md` exist. If either is missing: **STOP. Do NOT proceed to Part D or the Exit Gate.** Re-invoke the designer with corrected context. If a second attempt also fails, use `question` to report the failure and ask whether to retry or skip design.
+
+### Part C — Executive Summary (direct)
+
+Read `outputs/high-level-design.md` and `outputs/decision-log.md`, then present the executive summary through the Exit-Gate results box below (architecture style and key components, decision count, key decision highlights 1 line each, integration points with the existing system if applicable) — no separate presentation round.
+
+### Part D — Diagram Refinement (Skill, content-preserving)
+
+1. **INVOKE NOW**: Skill tool - `diagrams-mermaid` to refine visual communication in `outputs/high-level-design.md`.
+2. 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.
+3. If minimum context for a diagram is missing, record explicit gaps in the document and avoid speculative components/relationships.
+
+### Close (`design-generated`)
+
+1. **State write**: append `design-generated` to `completed_phases` after the SELF-CHECK passes and Part D completes; update `research_context.phase_summaries.design {summary, architecture_style, decisions_count}` (keep the Part A preferences visible in `summary`); set `research_outputs.high_level_design` AND `research_outputs.decision_log`; bump `orchestrator.updated`. On failure: append `design-generated` to `failed_phases`, increment `auto_fix_attempts["design-generated"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`design-generated`) plus that step's fields. Never batch multiple steps into one end-of-skill write.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if the designer delegation fails or its retries are abandoned, do NOT append `design-generated` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["design-generated"]`. A user-chosen skip via `question` after repeated failures is a deliberate decision, not a failure: record the reason in `phase_summaries.design.summary` and append neither `design-generated` nor a `failed_phases` entry. Then present the Exit Gate (results box notes the skip; next step is `/owflow:research-finalize <task-path>`).
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                          | Max Attempts | Strategy                                       |
+| ----------------------------- | ------------ | ----------------------------------------------- |
+| Design (`design-generated`)   | 2            | Re-invoke solution-designer with adjusted context |
+
+## Exit Gate
+
+Present results, get user confirmation, then hand off (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. A user-chosen skip still uses this Exit Gate; its results box says the step was skipped and why, and the next step is `/owflow:research-finalize <task-path>`.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH DESIGN COMPLETE — <research question>
+
+**Architecture style** — [style and key components]
+**Decisions recorded** — [N architectural decisions in decision-log.md]
+**Key highlights** — [1 line per key decision]
+**Integration points** — [with the existing system, if applicable]
+**Diagrams** — [refined by diagrams-mermaid / gaps recorded]
+
+**Artifacts**
+
+- `outputs/high-level-design.md`
+- `outputs/decision-log.md`
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the architecture and decision log are good; continue.
+- **Adjust** — re-invoke the designer with the user's corrections (changed constraints or preferences), update state and artifacts, re-present the results box.
+- **Discuss** — walk through the architecture style or specific architectural decisions in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-design <task-path>`) and end.
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-finalize <task-path>` — `required` next: inventories all research outputs (including these design artifacts) and completes the task (`research-completed`). Remaining after: none — development starts from finalize's handoff (`→ /owflow:development <task-path>`).
+
+Then STOP.

package/dist/skills/research-finalize/SKILL.md

@@ -1,125 +1,125 @@
----
-name: owflow:research-finalize
-description: Research skill — terminal step. Inventories all research outputs (research report always; brainstorm/design artifacts conditionally), presents the workflow results box, and gets user confirmation that the research is correct. Marks the task research-completed — the Exit-Gate acceptance here is where the goal-research wrapper's loop ends.
-argument-hint: "[task-path-or-identifier]"
-user-invocable: true
----
-
-# Research Finalize — Completion & Handoff (research-completed)
-
-Terminal step of the research workflow. Presents research results, confirms correctness with the user, and hands off to development (or ends the workflow). No new files — summarizes existing outputs. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
-
-Related phases: all research subskills (`/owflow:research-plan` → `/owflow:research-gather` → `/owflow:research-synthesize` → the optional chain as chosen by the user). This is the terminal skill: its Exit-Gate acceptance is where the goal-research wrapper's loop ends, and where assisted mode suggests development.
-
-## Entry Gate
-
-Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
-
-- **Path** (absolute or project-relative) to the task directory — use as-is.
-- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
-- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
-  1. Steps that must be completed first (in order), each with its command:
-     - Research brief & plan (`brief-written`, `plan-created`) → `/owflow:research-plan <task-path>`
-     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
-     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
-  2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
-  3. Hint: `Run /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
-
-### Prerequisites
-
-| Required for this skill | Where verified                                                                  | Produced by                                                        |
-| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| State file exists       | `<task-path>/orchestrator-state.yml`                                             | `/owflow:research <question>` or `/owflow:research-quick` |
-| Foundation complete     | `synthesis-complete` in `completed_phases` + `outputs/research-report.md` exists | `/owflow:research-synthesize <task-path>`                          |
-
-1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `research-completed`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch.` and STOP.
-2. **Prerequisite check**: `synthesis-complete` must be in `completed_phases` and `outputs/research-report.md` must exist. The optional chain is settled by the user's own choices — invoking `research-brainstorm`/`research-design` is the decision to run them; skipping straight here settles the chain as skipped. If the foundation is missing → print the blocked block for the earliest missing step, then STOP:
-   - `Run /owflow:research-plan <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-gather` or `/owflow:research-synthesize`).
-   - If no task exists yet: `Run /owflow:research <question> to start a task from scratch.`
-3. **Skip/resume**: if `task.status` is `completed`, report the existing finalization (results box from the inventory below) and STOP (dev-finalize terminal pattern).
-4. **Always runs**: this skill always runs — every path (no optional steps / design-only / full brainstorm chain) reaches completion here. The optional phases only affect the inventory and the "Phases run" line.
-
-## Input / Output Artifacts
-
-| Artifact                                       | Normal mode (full lane)                                        | Quick mode (`research-quick`)                                                    |
-| ---------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Consumed: `outputs/research-report.md` (always) + conditional design/brainstorm artifacts | inventoried per `research_outputs.*` in state | identical — a quick-pass task brings the same standard artifacts                             |
-| Produced: none (state-only)                    | no new files — finalization is an inventory                         | same — after a quick pass this skill completes the task the same way                        |
-| State write                                    | `research-completed`; `task.status: completed`                     | same slug and field                                                                    |
-
-## Execute (direct — inline-legal finalization)
-
-**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — finalization is inline-legal ("finalization" is a simple, direct step; no agents involved).
-
-### Inventory outputs
-
-1. **Inventory all generated outputs**: `outputs/research-report.md` (always), plus conditional: `outputs/solution-exploration.md`, `outputs/high-level-design.md`, `outputs/decision-log.md` — each conditional artifact is listed only when its `research_outputs` field is set in state (and the file exists).
-2. **Results box**:
-
-```markdown
-## ✅ RESEARCH COMPLETE — <research question>
-
-**Type** — [research type]
-**Confidence** — [confidence level]
-**Phases run** — [executed slug list, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated]
-**Key findings** — [2-3 one-line highlights]
-**Decisions** — [count of ADRs, if design ran]
-
-**Artifacts**
-
-- `outputs/research-report.md`
-- `outputs/solution-exploration.md` [conditional]
-- `outputs/high-level-design.md` [conditional]
-- `outputs/decision-log.md` [conditional]
-```
-
-### Close (`research-completed`)
-
-1. **State write**: append `research-completed` to `completed_phases` and set `task.status: completed` — ONLY after the results box is presented; do NOT write a `phase_summaries.finalize` slot (the template has no finalize slot — finalization is state-only, and the inventory lives in `research_outputs.*`); bump `orchestrator.updated`. On failure: append `research-completed` to `failed_phases`, increment `auto_fix_attempts["research-completed"]`. Then re-read state + run `verify_template` (see State Update Convention).
-
-## State Update Convention (per step)
-
-Apply after EVERY step above:
-
-1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`research-completed`) plus that step's fields. Never batch multiple steps into one end-of-skill write. **No `phase_summaries.finalize` write** — the template has no such slot (finalization is state-only; the inventory lives in `research_outputs.*`).
-2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
-3. **Failures** — if finalization fails, do NOT append `research-completed` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["research-completed"]`.
-4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
-5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
-
-## Recovery
-
-| Step                              | Max Attempts | Strategy      |
-| --------------------------------- | ------------ | -------------- |
-| Completion (`research-completed`) | 0            | Summary only   |
-
-## Exit Gate
-
-Present results, get user confirmation, then close the workflow (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. **This acceptance is where the goal-research wrapper's loop ends** (Accept = the wrapper proceeds to its own wrapper Exit Gate; any other option ends the loop with the standard handoff block). In assisted mode, Accept prints the next steps below.
-
-### Results box
-
-The results box from the Inventory outputs step above IS the workflow-level results box — present it here as-is (single box, not two).
-
-### Results-acceptance question
-
-Use `question` — "Are these results correct?" with options:
-
-- **Accept** — research is complete; print next steps (below).
-- **Adjust** — re-run the affected phase (re-gather → `/owflow:research-gather <task-path>`, re-brainstorm → `/owflow:research-brainstorm <task-path>`, re-design → `/owflow:research-design <task-path>`) with the user's corrections, then re-present the results box.
-- **Discuss** — walk through specific findings or decisions in more depth; then re-ask.
-- **Fork** — branch instead of re-running here: `/owflow:research-fork <task-path>` copies this task to a new one diverging at a chosen completed step (source untouched); pass a description to skip the intent question.
-- **Stop here** — print the resume command (`/owflow:research-finalize <task-path>`) and end.
-
-### Next steps (after Accept)
-
-If design artifacts exist (research report + design → development handoff), suggest starting development in a fresh session:
-
-```
-To start development based on this research, clear context first or start a new session, then run:
-→ /owflow:development <task-path>
-```
-
-Without design artifacts, the research report remains the deliverable — feed it into `/owflow:development <task-path>` the same way when development is ready, or reference it manually.
-
-Then STOP.
+---
+name: owflow:research-finalize
+description: Research skill — terminal step. Inventories all research outputs (research report always; brainstorm/design artifacts conditionally), presents the workflow results box, and gets user confirmation that the research is correct. Marks the task research-completed — the Exit-Gate acceptance here is where the goal-research wrapper's loop ends.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Finalize — Completion & Handoff (research-completed)
+
+Terminal step of the research workflow. Presents research results, confirms correctness with the user, and hands off to development (or ends the workflow). No new files — summarizes existing outputs. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: all research subskills (`/owflow:research-plan` → `/owflow:research-gather` → `/owflow:research-synthesize` → the optional chain as chosen by the user). This is the terminal skill: its Exit-Gate acceptance is where the goal-research wrapper's loop ends, and where assisted mode suggests development.
+
+## Entry Gate
+
+Resolve the `task-path-or-identifier` argument BEFORE anything else (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+- **Path** (absolute or project-relative) to the task directory — use as-is.
+- **Identifier** — exact directory name inside `.owflow/tasks/research/` (e.g., `2026-09-26-my-research`); resolve to its path.
+- If the argument is **missing**, the path does **not exist**, or matches **no identifier** → print the blocked block, then STOP (never guess or auto-pick a task):
+  1. Steps that must be completed first (in order), each with its command:
+     - Research brief & plan (`brief-written`, `plan-created`) → `/owflow:research-plan <task-path>`
+     - Parallel findings fan (`findings-gathered`) → `/owflow:research-gather <task-path>`
+     - Synthesis & research report (`synthesis-complete`) → `/owflow:research-synthesize <task-path>`
+  2. List available research-task identifiers (directories under `.owflow/tasks/research/`) to resume from, if any.
+  3. Hint: `Run /owflow:research <question> to start a task from scratch, or pass a task path/identifier to resume.`
+
+### Prerequisites
+
+| Required for this skill | Where verified                                                                  | Produced by                                                        |
+| ----------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| State file exists       | `<task-path>/orchestrator-state.yml`                                             | `/owflow:research <question>` or `/owflow:research-quick` |
+| Foundation complete     | `synthesis-complete` in `completed_phases` + `outputs/research-report.md` exists | `/owflow:research-synthesize <task-path>`                          |
+
+1. **Read `orchestrator-state.yml`** from the task path. If missing → mid-pipeline bootstrap ([Missing-state Bootstrap](../orchestrator-framework/references/gate-contract.md), starting slug `research-completed`): `question` — create a fresh standard research task starting at this step, or decline → print `No research task found at <path>. Run /owflow:research <question> to start a task from scratch.` and STOP.
+2. **Prerequisite check**: `synthesis-complete` must be in `completed_phases` and `outputs/research-report.md` must exist. The optional chain is settled by the user's own choices — invoking `research-brainstorm`/`research-design` is the decision to run them; skipping straight here settles the chain as skipped. If the foundation is missing → print the blocked block for the earliest missing step, then STOP:
+   - `Run /owflow:research-plan <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-gather` or `/owflow:research-synthesize`).
+   - If no task exists yet: `Run /owflow:research <question> to start a task from scratch.`
+3. **Skip/resume**: if `task.status` is `completed`, report the existing finalization (results box from the inventory below) and STOP (dev-finalize terminal pattern).
+4. **Always runs**: this skill always runs — every path (no optional steps / design-only / full brainstorm chain) reaches completion here. The optional phases only affect the inventory and the "Phases run" line.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                        | Quick mode (`research-quick`)                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Consumed: `outputs/research-report.md` (always) + conditional design/brainstorm artifacts | inventoried per `research_outputs.*` in state | identical — a quick-pass task brings the same standard artifacts                             |
+| Produced: none (state-only)                    | no new files — finalization is an inventory                         | same — after a quick pass this skill completes the task the same way                        |
+| State write                                    | `research-completed`; `task.status: completed`                     | same slug and field                                                                    |
+
+## Execute (direct — inline-legal finalization)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — finalization is inline-legal ("finalization" is a simple, direct step; no agents involved).
+
+### Inventory outputs
+
+1. **Inventory all generated outputs**: `outputs/research-report.md` (always), plus conditional: `outputs/solution-exploration.md`, `outputs/high-level-design.md`, `outputs/decision-log.md` — each conditional artifact is listed only when its `research_outputs` field is set in state (and the file exists).
+2. **Results box**:
+
+```markdown
+## ✅ RESEARCH COMPLETE — <research question>
+
+**Type** — [research type]
+**Confidence** — [confidence level]
+**Phases run** — [executed slug list, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated]
+**Key findings** — [2-3 one-line highlights]
+**Decisions** — [count of ADRs, if design ran]
+
+**Artifacts**
+
+- `outputs/research-report.md`
+- `outputs/solution-exploration.md` [conditional]
+- `outputs/high-level-design.md` [conditional]
+- `outputs/decision-log.md` [conditional]
+```
+
+### Close (`research-completed`)
+
+1. **State write**: append `research-completed` to `completed_phases` and set `task.status: completed` — ONLY after the results box is presented; do NOT write a `phase_summaries.finalize` slot (the template has no finalize slot — finalization is state-only, and the inventory lives in `research_outputs.*`); bump `orchestrator.updated`. On failure: append `research-completed` to `failed_phases`, increment `auto_fix_attempts["research-completed"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately** — update `orchestrator-state.yml` as soon as the step completes, appending ONLY the step slug actually performed (`research-completed`) plus that step's fields. Never batch multiple steps into one end-of-skill write. **No `phase_summaries.finalize` write** — the template has no such slot (finalization is state-only; the inventory lives in `research_outputs.*`).
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if finalization fails, do NOT append `research-completed` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["research-completed"]`.
+4. **Validate** — after every write, re-read the file to confirm values, then run the `verify_template` tool with `filePath: <task-path>/orchestrator-state.yml`, `templateName: orchestrator-state-research.yml`. Fix any reported issue immediately before proceeding.
+5. **Final check** — before the Exit Gate, one consolidated re-read + `verify_template` run to confirm the full state matches everything performed in this session.
+
+## Recovery
+
+| Step                              | Max Attempts | Strategy      |
+| --------------------------------- | ------------ | -------------- |
+| Completion (`research-completed`) | 0            | Summary only   |
+
+## Exit Gate
+
+Present results, get user confirmation, then close the workflow (see [Gate Contract](../orchestrator-framework/references/gate-contract.md)). Never auto-invoke the next skill. **This acceptance is where the goal-research wrapper's loop ends** (Accept = the wrapper proceeds to its own wrapper Exit Gate; any other option ends the loop with the standard handoff block). In assisted mode, Accept prints the next steps below.
+
+### Results box
+
+The results box from the Inventory outputs step above IS the workflow-level results box — present it here as-is (single box, not two).
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — research is complete; print next steps (below).
+- **Adjust** — re-run the affected phase (re-gather → `/owflow:research-gather <task-path>`, re-brainstorm → `/owflow:research-brainstorm <task-path>`, re-design → `/owflow:research-design <task-path>`) with the user's corrections, then re-present the results box.
+- **Discuss** — walk through specific findings or decisions in more depth; then re-ask.
+- **Fork** — branch instead of re-running here: `/owflow:research-fork <task-path>` copies this task to a new one diverging at a chosen completed step (source untouched); pass a description to skip the intent question.
+- **Stop here** — print the resume command (`/owflow:research-finalize <task-path>`) and end.
+
+### Next steps (after Accept)
+
+If design artifacts exist (research report + design → development handoff), suggest starting development in a fresh session:
+
+```
+To start development based on this research, clear context first or start a new session, then run:
+→ /owflow:development <task-path>
+```
+
+Without design artifacts, the research report remains the deliverable — feed it into `/owflow:development <task-path>` the same way when development is ready, or reference it manually.
+
+Then STOP.