owflow 0.6.0 → 0.7.0

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

@@ -1,130 +1,130 @@
----
-name: owflow:research-converge
-description: Research skill — optional subskill. Presents the brainstorming alternatives for EVERY decision area with identical full detail — one area, one question — records each chosen approach in phase_summaries.converge.decision_areas (approaches-chosen). Never a combined summary-table confirm.
-argument-hint: "[task-path-or-identifier]"
-user-invocable: true
----
-
-# Research Converge — Per-Area Decisions (approaches-chosen)
-
-Work phase of the research workflow. Interactive convergence: presents the brainstorming alternatives for each decision area — one area, one dedicated `question` — and records the chosen combination in state (state-only; no new artifacts). Conditional optional phase — runs only when brainstorming ran. There is no auto-continue from brainstorm: this skill's Entry Gate re-checks the artifact. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
-
-Related phases: `/owflow:research-brainstorm` (produces `outputs/solution-exploration.md`, which this skill parses), `/owflow:research-design` (consumes the chosen combination as `selected_approach`), `/owflow:research-finalize` (the route when design is off).
-
-## 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>`
-     - Solution alternatives (`alternatives-generated`) → `/owflow:research-brainstorm <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` + `analysis/synthesis.md` exists                 | `/owflow:research-synthesize <task-path>`                          |
-| Alternatives exist      | `alternatives-generated` in `completed_phases` + `outputs/solution-exploration.md` exists   | `/owflow:research-brainstorm <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 `approaches-chosen`): `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` AND `alternatives-generated` must be in `completed_phases`, and `outputs/solution-exploration.md` must exist. If missing → print the blocked block, then STOP:
-   - `Run /owflow:research-brainstorm <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-plan`, `/owflow:research-gather`, or `/owflow:research-synthesize`).
-3. **Skip/resume (per-area partial resume)**: if `approaches-chosen` is in `completed_phases`, validate every `phase_summaries.converge.decision_areas` entry carries `chosen_approach` — all resolve → report the existing chosen combination and route to the Exit Gate; any area unresolved → re-ask ONLY the unresolved areas below. Also — even WITHOUT the slug — skip any area whose `decision_areas` entry already carries `chosen_approach`; only unresolved areas are ever asked.
-
-## Input / Output Artifacts
-
-| Artifact                                       | Normal mode (full lane)                                                | Quick mode (`research-quick`)                                                                          |
-| ---------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Consumed: `outputs/solution-exploration.md`    | parsed for decision areas + alternatives                                | identical — when the optional chain runs after a quick pass, the exploration file was produced by research-brainstorm |
-| Produced: none (state-only)                    | decisions recorded inline per area                                      | same mechanics — research-quick never converges inline                                                     |
-| State write                                    | `approaches-chosen`; `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (per-area partial writes) | same slug and fields                                                          |
-
-## Execute (direct interactive — per-area convergence)
-
-**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — per-area convergence is direct interactive work (like dev-verify's interactive phases); no agents involved.
-
-> **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.
-
-**Per-area handling** (the two guards above apply to EVERY area, including partial resumes):
-
-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 (write the per-area partial state immediately — see State Update Convention), 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 (this summary moves into the Exit-Gate results box below — the boundary to design/finalize stays explicit, no AUTO-CONTINUE)
-4. **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 the convergence complete without user convergence on all decision areas.
-
-### Close (`approaches-chosen`)
-
-1. **State write**: append `approaches-chosen` to `completed_phases` — ONLY after the LAST unresolved area resolves; update `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (deferred ideas recorded when the exploration documents them); bump `orchestrator.updated`. On failure: append `approaches-chosen` to `failed_phases`, increment `auto_fix_attempts["approaches-chosen"]`. Then re-read state + run `verify_template` (see State Update Convention).
-
-## State Update Convention (per step)
-
-Apply after EVERY step above:
-
-1. **Write immediately — per area**: as each decision area resolves, record the `chosen_approach` into that area's entry in `phase_summaries.converge.decision_areas` immediately (never batch all areas into one end-of-skill write — the per-area write is what makes partial resume work). The `approaches-chosen` slug is appended ONLY after the LAST unresolved area resolves.
-2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
-3. **Failures** — if a question cannot fire (read failure, tool failure) or an area could not resolve, do NOT append `approaches-chosen` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["approaches-chosen"]`. A deliberate "stop here" at an area question is NOT a failure — the area simply stays unresolved and partial resume picks it up on the next run.
-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                                    |
-| ------------------------------- | ------------ | -------------------------------------------- |
-| Converge (`approaches-chosen`)  | 1            | Re-read exploration file, re-present areas   |
-
-## 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. The chosen-combination summary (step 3 above) is folded into the results box.
-
-### Results box
-
-```markdown
-## ✅ RESEARCH CONVERGE COMPLETE — <research question>
-
-**Decision areas** — [N areas resolved]
-**Chosen combination** — [area: choice, one line per area]
-**Deferred ideas** — [one line each / none]
-**Design decision** — [feeds into design as `selected_approach` / no design planned]
-
-**Artifacts**
-
-- none (state-only) — decisions live in `phase_summaries.converge.decision_areas` of `orchestrator-state.yml`; `outputs/solution-exploration.md` stays the shared record
-```
-
-### Results-acceptance question
-
-Use `question` — "Are these results correct?" with options:
-
-- **Accept** — the per-area decisions are good; continue.
-- **Adjust** — re-open a specific area: re-present that ONE area with full detail and re-ask its question (other areas untouched), update state, re-present the results box.
-- **Discuss** — walk through a specific area's trade-offs in more depth; then re-ask.
-- **Stop here** — print the resume command (`/owflow:research-converge <task-path>`) and end. Note: unresolved areas re-ask on the next run (per-area partial resume).
-
-### Next steps (after Accept)
-
-- `→ /owflow:research-design <task-path>` — when the user wants high-level design: Part A asks design preferences, Part B delegates the solution-designer with the chosen combination as `selected_approach`, Part D refines diagrams. Remaining after: finalize.
-- `→ /owflow:research-finalize <task-path>` — when no design is wanted: inventories the research outputs and completes the task (`research-completed`). Remaining after: none.
-
-Then STOP.
+---
+name: owflow:research-converge
+description: Research skill — optional subskill. Presents the brainstorming alternatives for EVERY decision area with identical full detail — one area, one question — records each chosen approach in phase_summaries.converge.decision_areas (approaches-chosen). Never a combined summary-table confirm.
+argument-hint: "[task-path-or-identifier]"
+user-invocable: true
+---
+
+# Research Converge — Per-Area Decisions (approaches-chosen)
+
+Work phase of the research workflow. Interactive convergence: presents the brainstorming alternatives for each decision area — one area, one dedicated `question` — and records the chosen combination in state (state-only; no new artifacts). Conditional optional phase — runs only when brainstorming ran. There is no auto-continue from brainstorm: this skill's Entry Gate re-checks the artifact. State lives in `orchestrator-state.yml` — this skill reads it on entry and writes results on exit.
+
+Related phases: `/owflow:research-brainstorm` (produces `outputs/solution-exploration.md`, which this skill parses), `/owflow:research-design` (consumes the chosen combination as `selected_approach`), `/owflow:research-finalize` (the route when design is off).
+
+## 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>`
+     - Solution alternatives (`alternatives-generated`) → `/owflow:research-brainstorm <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` + `analysis/synthesis.md` exists                 | `/owflow:research-synthesize <task-path>`                          |
+| Alternatives exist      | `alternatives-generated` in `completed_phases` + `outputs/solution-exploration.md` exists   | `/owflow:research-brainstorm <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 `approaches-chosen`): `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` AND `alternatives-generated` must be in `completed_phases`, and `outputs/solution-exploration.md` must exist. If missing → print the blocked block, then STOP:
+   - `Run /owflow:research-brainstorm <task-path> first` (or the command for the earliest missing earlier step: `/owflow:research-plan`, `/owflow:research-gather`, or `/owflow:research-synthesize`).
+3. **Skip/resume (per-area partial resume)**: if `approaches-chosen` is in `completed_phases`, validate every `phase_summaries.converge.decision_areas` entry carries `chosen_approach` — all resolve → report the existing chosen combination and route to the Exit Gate; any area unresolved → re-ask ONLY the unresolved areas below. Also — even WITHOUT the slug — skip any area whose `decision_areas` entry already carries `chosen_approach`; only unresolved areas are ever asked.
+
+## Input / Output Artifacts
+
+| Artifact                                       | Normal mode (full lane)                                                | Quick mode (`research-quick`)                                                                          |
+| ---------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Consumed: `outputs/solution-exploration.md`    | parsed for decision areas + alternatives                                | identical — when the optional chain runs after a quick pass, the exploration file was produced by research-brainstorm |
+| Produced: none (state-only)                    | decisions recorded inline per area                                      | same mechanics — research-quick never converges inline                                                     |
+| State write                                    | `approaches-chosen`; `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (per-area partial writes) | same slug and fields                                                          |
+
+## Execute (direct interactive — per-area convergence)
+
+**Read first**: the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md) — per-area convergence is direct interactive work (like dev-verify's interactive phases); no agents involved.
+
+> **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.
+
+**Per-area handling** (the two guards above apply to EVERY area, including partial resumes):
+
+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 (write the per-area partial state immediately — see State Update Convention), 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 (this summary moves into the Exit-Gate results box below — the boundary to design/finalize stays explicit, no AUTO-CONTINUE)
+4. **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 the convergence complete without user convergence on all decision areas.
+
+### Close (`approaches-chosen`)
+
+1. **State write**: append `approaches-chosen` to `completed_phases` — ONLY after the LAST unresolved area resolves; update `phase_summaries.converge {summary, decision_areas, deferred_ideas}` (deferred ideas recorded when the exploration documents them); bump `orchestrator.updated`. On failure: append `approaches-chosen` to `failed_phases`, increment `auto_fix_attempts["approaches-chosen"]`. Then re-read state + run `verify_template` (see State Update Convention).
+
+## State Update Convention (per step)
+
+Apply after EVERY step above:
+
+1. **Write immediately — per area**: as each decision area resolves, record the `chosen_approach` into that area's entry in `phase_summaries.converge.decision_areas` immediately (never batch all areas into one end-of-skill write — the per-area write is what makes partial resume work). The `approaches-chosen` slug is appended ONLY after the LAST unresolved area resolves.
+2. **Timestamp** — set `orchestrator.updated` to the current UTC timestamp on every write.
+3. **Failures** — if a question cannot fire (read failure, tool failure) or an area could not resolve, do NOT append `approaches-chosen` to `completed_phases`; instead append it to `orchestrator.failed_phases` and increment `auto_fix_attempts["approaches-chosen"]`. A deliberate "stop here" at an area question is NOT a failure — the area simply stays unresolved and partial resume picks it up on the next run.
+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                                    |
+| ------------------------------- | ------------ | -------------------------------------------- |
+| Converge (`approaches-chosen`)  | 1            | Re-read exploration file, re-present areas   |
+
+## 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. The chosen-combination summary (step 3 above) is folded into the results box.
+
+### Results box
+
+```markdown
+## ✅ RESEARCH CONVERGE COMPLETE — <research question>
+
+**Decision areas** — [N areas resolved]
+**Chosen combination** — [area: choice, one line per area]
+**Deferred ideas** — [one line each / none]
+**Design decision** — [feeds into design as `selected_approach` / no design planned]
+
+**Artifacts**
+
+- none (state-only) — decisions live in `phase_summaries.converge.decision_areas` of `orchestrator-state.yml`; `outputs/solution-exploration.md` stays the shared record
+```
+
+### Results-acceptance question
+
+Use `question` — "Are these results correct?" with options:
+
+- **Accept** — the per-area decisions are good; continue.
+- **Adjust** — re-open a specific area: re-present that ONE area with full detail and re-ask its question (other areas untouched), update state, re-present the results box.
+- **Discuss** — walk through a specific area's trade-offs in more depth; then re-ask.
+- **Stop here** — print the resume command (`/owflow:research-converge <task-path>`) and end. Note: unresolved areas re-ask on the next run (per-area partial resume).
+
+### Next steps (after Accept)
+
+- `→ /owflow:research-design <task-path>` — when the user wants high-level design: Part A asks design preferences, Part B delegates the solution-designer with the chosen combination as `selected_approach`, Part D refines diagrams. Remaining after: finalize.
+- `→ /owflow:research-finalize <task-path>` — when no design is wanted: inventories the research outputs and completes the task (`research-completed`). Remaining after: none.
+
+Then STOP.

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` (the skill writes the diagrams into the file and themes them github-dark by default).
+2. Add diagrams that supplement (NOT replace) existing architecture content:
+   - one architecture view (`flowchart` with subgraphs; nested subgraphs 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.