opsx-solve-workflow

name	opsx-solve-workflow
version	1.15.0
user-invocable	true
description	Eight-stage PDCA problem-solving workflow that persists analysis, proposal, design review, plan, execution, and verification into OpenSpec artifacts (openspec/changes/<name>/, archived into openspec/specs/) instead of leaving them only in chat context. Use for feature work, bug fixes, refactors, and complex engineering tasks that need long-term behavioral-contract traceability, team review, or auditability. Do NOT use for a quick one-off edit with no traceability need — use solve-workflow instead. Triggers：「opsx解决」「OpenSpec解决」「规范化解决」「创建OpenSpec变更」「创建opsx变更」「用OpenSpec分析」「用OpenSpec修复」「opsx自动解决」「OpenSpec自动解决」「opsx-solve」「opsx-solve-workflow」 / opsx solve, OpenSpec solve workflow, create an OpenSpec change.
dependencies	["solution-review","code-design-review","hybrid-debug","runtime-evidence-debug","browser-debug-toolkit","node-version-discipline","learn-and-improve","workflow-mode-lifecycle","clarifying-question-discipline","known-issue-research","analysis-core","test-suite-ensure","merge-discipline","staged-review-flow","opsx-workspace-gate","completion-evidence-discipline","domain-language-discipline","test-first-discipline","design-approval-gate","delivery-discipline","feature-branch-closeout","decision-fog-discipline","workspace-isolation-discipline"]

OPSX Eight-Stage Problem-Solving Workflow

Combines solve-workflow's eight-stage PDCA discipline with OpenSpec/OPSX artifact persistence. The goal: never let the AI skip analysis, proposal, review, or verification, and never let the key conclusions live only in chat context.

Output templates: see reference.md for each stage's format.

Positioning

Use this skill for engineering changes that are worth persisting: requirements, root cause, behavior changes, technical trade-offs, task lists, and verification results should all be written to openspec/changes/<change-name>/, then merged into openspec/specs/ via archive on completion.

Division of labor:

• OpenSpec: the source of truth and archive system — answers "what, and why".
• solve-workflow-style gates: stage gating — answers "when is it allowed to move to the next step".

Not a replacement for plain solve-workflow:

• Quick fixes, single-file lightweight edits, or tasks needing no long-term traceability — prefer solve-workflow.
• Tasks involving long-term behavioral contracts, team review, concurrent changes, requirement audits, or later traceability — use this skill.

Invocation conventions

• Triggers: opsx解决, OpenSpec解决, 规范化解决, 创建OpenSpec变更, 创建opsx变更, 用OpenSpec分析, 用OpenSpec修复, opsx自动解决, OpenSpec自动解决, opsx-solve, opsx-solve-workflow
• Mode: a trigger containing "自动" (auto) enters auto mode; otherwise manual mode by default.
• Manual mode: the key exits of stages 1, 2, 3, 4, 5, 7, 8 must wait for user confirmation.
• Auto mode: auto-advances through to verification; the stage 4 review loop caps at 3 rounds, then pauses.

Strong-dependency skills (frontmatter dependencies; must pass the "Prerequisite skill check" at startup — abort if any is missing):

• staged-review-flow (stage 4 review orchestration; depends on solution-review and code-design-review)
• hybrid-debug / runtime-evidence-debug / browser-debug-toolkit (delegated via analysis-core; stage 2 + stage 7)
• analysis-core (single source for stage-2 analysis methodology: temporary-change gate / instrumentation debug / analysis step skeleton / debug-verify loop)
• node-version-discipline (stage 7 Node version alignment)
• learn-and-improve (stage 8 retrospective and knowledge sediment)
• workflow-mode-lifecycle (auto/manual mode lifecycle)
• clarifying-question-discipline (hard discipline for active questioning + investigation-first)
• known-issue-research (stage 2 research routing / known-issue quick search / industry-wide evaluation)
• test-suite-ensure (stage 6 test-suite ensure: complete and run tests when infra exists; scaffold with user confirmation when it doesn't)
• test-first-discipline (stage 6: failing-test-first for behavior changes; distinct from test-suite-ensure)
• design-approval-gate (before stage 6: no production impl without approval; named auto/hotfix escapes)
• delivery-discipline (stage 8: optional commit + open/update PR/MR after archive; not every run delivers)
• feature-branch-closeout (stage 8: post-archive closeout menu; merge delegates to merge-discipline)
• decision-fog-discipline (before explore solutions: graduate fog / decision tickets first)
• workspace-isolation-discipline (before stage 6: optional isolated workspace)
• domain-language-discipline (clarify/analyze: project glossary / CONTEXT.md when domain terms matter)
• merge-discipline (stage 8 merge discipline — after closeout selects merge)
• opsx-workspace-gate (stage 0 OpenSpec workspace and native-skill gate)

Prerequisite skill check

At startup (after the stage-0 gate passes, before stage 1), check frontmatter dependencies: scan available skills, and if any is missing → print a structured prompt and abort immediately (format: solve-workflow/reference.md「Prerequisite Skill Check — Missing Notice」).

No-degradation principle: a missing strong dependency means abort — never fall back to a simplified review or debug flow.

Mode lifecycle

Entry, persistence, and exit rules for auto mode, preventing mode stickiness where the user is unaware the AI is still making automatic decisions. The core rules (revert-to-manual / explicit re-entry / implicit continuation never re-activates / batch scenarios) live in the strong-dependency skill workflow-mode-lifecycle (already guaranteed available by the prerequisite check) — not restated here.

OpenSpec-specific notes

• After stage 8 archiving completes, mode auto-reverts to manual.
• If the user decides to start another PDCA round (back to stage 3/4/5), it defaults to manual mode.
• An archive interruption (e.g. the openspec-archive-change skill fails) also counts as a flow interruption — revert to manual.

---

Stage 0: Environment check & path selection

This skill requires a fully initialized OpenSpec workspace; there is no degraded path. Load opsx-workspace-gate and run its project-root location, openspec/ check, and exact native-OPSX-skill gate; once it passes, this workflow keeps its own stage gating and downstream orchestration.

Prep steps after passing the gate

1. Decide whether to use an existing change or create a new one, and prepare only a candidate name:
   • If the user names a change, prefer using it.
   • Otherwise generate a kebab-case candidate name for the new work, and confirm it with the user in manual mode.
2. Prepare the creation method, but do not create the directory before the stage-1 user confirmation: create the change via the openspec-new-change skill (read its SKILL.md, then follow its instructions).

Path selection

Pick a path per the task and declare it before continuing:

Path	Fits	Requirements
Full	Brand-new feature, complex module, fuzzy requirements	Run stages 1-8 in full
Incremental	Existing-behavior change, refactor, ordinary bug	Run stages 1-8, but proposal/spec may stay lean
Lean	Hotfix, small high-certainty change	Keep proposal, delta spec, tasks, verification, and archive — never skip verification

If scope expands mid-execution, the path must be upgraded: lean → incremental, incremental → full. In manual mode, an upgrade needs user confirmation.

Stage-to-artifact mapping

Stage	Goal	OpenSpec landing spot	Code writes
1. Clarify the problem	Align on the problem, extract elements, resolve open questions	Analysis only, no artifact	Forbidden
2. Analyze the problem	Confirm existence, locate root cause, assess impact	Analysis only, no artifact (conclusions land in proposal.md after stage 3)	Forbidden
3. Explore solutions	Present 2-5 solutions and pick one	proposal.md (complete) + specs/<capability>/spec.md (delta specs), via openspec-continue-change	Forbidden
4. Review the solution	Review validity, risk, feasibility	design.md (via openspec-continue-change)	Forbidden
5. Make the plan	Break into executable tasks	tasks.md (via openspec-continue-change)	Forbidden
6. Execute the plan	Implement per task and check them off; once all tasks are done call test-suite-ensure to make sure the test suite is in place	Update tasks.md checkboxes (via openspec-apply-change); test files (generated by test-suite-ensure)	Allowed
7. Check & verify	Test, validate, cross-check against artifacts	Verification conclusions (via the openspec-verify-change skill or openspec validate)	Forbidden
8. Review & archive	Land the result or start another round	openspec/specs/ update + move into openspec/changes/archive/ (via the openspec-archive-change skill)	Archive/docs only

Stages 1-5 forbid modifying business code but allow creating and updating OpenSpec artifacts. If the user asks to "just analyze, don't persist", output stage conclusions only and skip writing artifacts.

Stage 1: Clarify the problem

⚠️ Active questioning: follow clarifying-question-discipline (one question per round, multi-round until clear; clarify first, don't rush to answer). When domain vocabulary is in play, also follow domain-language-discipline.

Manual mode must complete the following steps in order:

1. Restate the problem — describe the user's problem in your own words.
2. Extract key elements — goal, constraints, background, expected outcome.
3. List open questions — enumerate points needing further confirmation; if asking the user, ask only the single most critical one at a time, then ask the next only after getting an answer. 3.5. Scope breakdown (if applicable) — if the problem spans multiple independent subsystems, help break it down first: independent modules, dependencies, suggested handling order — then enter stage-2 technical analysis for the first sub-problem.
4. Wait for user confirmation.

Tool restriction: Read/Grep/SemanticSearch are forbidden, with these exceptions:

• The user's message contains @file-path (optionally with line numbers)
• The user's message pastes a code snippet
• The user explicitly names a "function/class name + its file" combination

Under an exception: read only the file and lines the user directly referenced, never expand to other files. The read result only aids understanding of the problem — no technical-analysis conclusion may appear in the stage-1 output.

Output format for manual mode: see reference.md「Stage 1 Clarify the Problem」.

Do not create a change or modify any file before user confirmation. After confirmation:

1. Create the change directory via the openspec-new-change skill (read its SKILL.md, then follow its instructions).
2. Record this round's path choice (full / incremental / lean).
3. Then proceed to stage-2 technical analysis.

Auto mode may skip the confirmation, but must still generate the candidate name first, then create the change immediately and continue.

Stage 2: Analyze the problem

Single source for analysis methodology: analysis-core. This stage leaves no implementation change — fixes belong in stage 6.

Delegate to analysis-core

Load the strong dependency analysis-core and execute its §§1-3. This workflow's mapping (number + name):

• {next-stage} = Stage 3 "Explore solutions"
• {root-cause step} = step 5; {impact-assessment step} = step 7; {upstream-eval step} = step 6

🔌 OPSX: this stage creates no artifact; Why / Impact are written into proposal.md once stage 3 selects a solution.

If the existence check fails or the description mismatches the code, pause for user confirmation and do not proceed to solution exploration.

---

Stage 3: Explore solutions

Principle: based on the stage-2 analysis, offer 2-5 solutions; strip non-essential features and over-engineering from every solution (YAGNI). If the path is still foggy, follow decision-fog-discipline before the solution table / proposal.

Produce 2-5 solutions based on stage 2, each including:

• Core idea
• Capabilities or behavior changes involved
• OpenSpec capabilities to add or modify
• Pros, cons, complexity, risk
• Recommended solution

In manual mode, output the comparison table and then pause for the user's pick.

🔌 OPSX skills integration: once a solution is selected, complete the following two steps via the openspec-continue-change skill (each call creates one artifact — read its SKILL.md first, then follow its instructions):

1. Create proposal.md (the change's first ready artifact): merge stage 2's root-cause analysis (Why / Impact) with this stage's solution selection (What Changes / Capabilities) into a complete proposal.
2. Create delta specs (specs become ready once the proposal is complete): write behavior changes into specs/<capability>/spec.md.

Delta-spec conventions (enforced by the openspec-continue-change skill):

• Only behavior changes: ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED Requirements
• Every requirement heading must be ### Requirement: <description containing SHALL or MUST>
• Every requirement must include at least one #### Scenario: block

Common mistakes: ### REQ-001: (wrong format), ### Requirement: Initialize (missing SHALL/MUST), no Scenario block. All three fail openspec validate. Format examples live in the openspec-continue-change skill.

Red flags — forbidden in stage 3

• Generating only 1 solution and skipping the comparison on the grounds that "the direction is already clear"
• Advancing to review in manual mode before the user picked a solution
• A solution carrying non-essential features or over-engineering (violates YAGNI)

Stage 4: Review the solution

Load staged-review-flow and execute its full review contract. This workflow's mapping: {next-stage} = Stage 5 "Make the plan"; {artifact-sink} = design.md created via openspec-continue-change; {extra-dimensions} = spec compliance (proposal's why, delta specs' behavior, design's risk, tasks' coverage of requirements); {batch-overcap-behavior} = N/A. After the review passes, create design.md via the native skill.

Non-blocking issues (may be noted as suggestions but don't block passing; never treat "a better architecture exists but the near-term one is maintainable" as blocking):

• Low-risk items with an existing mitigation
• Code-style preferences that don't affect correctness or structure
• Non-structural performance improvements deferrable to a later iteration
• Explicitly accepted Prudent-Deliberate technical debt (with a repayment plan)

Red flags — forbidden in stage 4

• Skipping the solution review and going straight to stage 5 (risks unidentified)
• Modifying code during the review stage (violates the read-only constraint)
• Not optimizing the solution when auto-mode review fails, and advancing to stage 5 anyway
• Auto-mode review loop exceeding the 3-round cap without pausing
• Auto-mode optimizing the solution without recording the optimization rationale, breaking review traceability
• The AI advancing on its own in manual mode when the user hasn't given an explicit pass/fail verdict

Stage 5: Make the plan

🔌 OPSX skills integration: generate tasks.md via the openspec-continue-change skill (read its SKILL.md first, then follow its instructions; tasks become ready once both specs and design are complete). This skill never hand-writes tasks.md content directly.

tasks.md conventions (enforced by the skill):

• Use checkboxes; tasks fine-grained enough; ordering reflects dependencies
• Include necessary test, verification, documentation, or migration steps
• No TBD, TODO, "handle appropriately", "similar to above", or other non-actionable descriptions

In manual mode, output the plan and pause; wait for user confirmation before entering stage 6.

Stage 6: Execute the plan

Before production edits, follow design-approval-gate (manual: user pass; auto/lean: named escape + 留痕). Optionally follow workspace-isolation-discipline before non-trivial edits.

Read tasks.md and implement in order:

1. Work on the single smallest current task at a time.
2. Before touching business code, confirm the relevant proposal, specs, design, and tasks already exist.
3. Update the checkbox immediately after finishing a task: use StrReplace to flip the corresponding [ ] to [x] in tasks.md — do not batch this until after a group of tasks. Skipping this makes the stage-7 verifier report a CRITICAL false-incomplete.
4. If implementation reveals the design or spec is inaccurate, update that artifact first, then continue implementing.
5. State the reason for any deviation from the plan; if the deviation affects scope or the behavioral contract, return to stage 4 or stage 5.

Test-first then test-suite ensure (mandatory, before the execution report)

For behavior-changing work, follow test-first-discipline (failing test observed before production code). Once every tasks.md checkbox is checked, before outputting the execution report, this step is mandatory:

Load and call test-suite-ensure, declaring mode=mandatory, scoped to this change's logic files; a failure or a declined necessary-scaffolding request blocks entry to stage 7. test-suite-ensure does not satisfy test-first.

🔌 OPSX skills integration: call the openspec-apply-change skill to execute the tasks (read its SKILL.md first, then complete each task per its instructions). openspec-apply-change queries change status and execution instructions via the CLI internally; this skill never calls the CLI directly to drive execution.

Stage 7: Check & verify

Verification must cover three layers:

1. OpenSpec validation:
   • If the openspec-verify-change skill is detected → read its SKILL.md and delegate verification to it.
   • If it's absent → run openspec validate <change-name> or openspec validate --changes directly (a CLI tool call, not a degradation).

Node version alignment (prerequisite): call node-version-discipline to align to the project's declared Node version before running the engineering-verification commands below.

2. Engineering verification: run the project's tests, type check, lint, or build (under the aligned version).
3. Behavior cross-check: confirm the implementation covers every delta-spec requirement and scenario, one by one.
4. Debug-verify loop: if stage 2 used a debug skill to locate the root cause, verify the fix using that same skill per analysis-core §4 (not tests alone).

Verification conclusions must be based on commands you ran and personally read the output of this round — never report "a scenario was designed" as "passed".

Output format: see reference.md「Stage 7 Check & Verify」.

Label each result per staged-review-flow's verification-report honesty rule and completion-evidence-discipline (no pass claims without fresh current-turn evidence).

Manual mode pauses here to wait for user confirmation before archiving. Do not archive on a failed verification — return to stage 4, 5, or 6 instead.

Test execution

If the stage-6 execution report involves tests (unit tests, integration tests, manual verification steps):

• AI can execute: use Bash to run test commands (e.g. npm test, pytest, go test) and fold the result into the check conclusion.
• AI cannot execute (no Bash, environment limits, tests need manual action): explicitly remind the user: "This change involves tests — please run [specific command/steps] yourself and confirm they pass before closing out."

Stage 8: Review & archive

If verification passed, run the pre-archive check:

• Are all tasks.md items complete?
• Do the delta specs represent the actual implementation?
• Will the main specs be updated correctly?
• Has the user confirmed archiving?

🔌 OPSX skills integration: before archiving:

1. If delta specs exist: call the openspec-sync-specs skill (if installed) to merge delta specs into the main specs/<capability>/spec.md, or let openspec-archive-change prompt for and handle the sync during archiving.
2. Execute the archive: call the openspec-archive-change skill (read its SKILL.md first, then follow its instructions).

If openspec-archive-change fails, do not manually manipulate the openspec/ directory — stop and tell the user to check the OpenSpec installation.

After archiving, always check the diff to confirm both the main-specs update and the archive-directory move landed in the project root's git working-tree changes. Then load delivery-discipline when this run may need commit + PR/MR (archive diffs usually need delivery; the skill's need-delivery gate may still skip). Then load feature-branch-closeout for the closeout menu (PR / merge / keep / continue). Never declare completion while tests haven't passed, archiving isn't complete, or the diff hasn't been reviewed.

Order constraint: archive + diff check → optional delivery-discipline → feature-branch-closeout → on merge, merge-discipline A→B→C→R→D. Choosing keep/continue does not trigger merge discipline.

Merge discipline (merge-discipline skill)

On merge (from closeout or a direct user merge command), load merge-discipline and run Part A → B → C → R → D; the pre-merge checklist is in merge-discipline/reference.md. Never implicitly skip.

Retrospective (delegate to learn-and-improve)

Once archiving and branch closeout are complete, load learn-and-improve and follow its framework; OpenSpec artifacts archived through the normal flow are not subject to its sediment-value gate.

OpenSpec artifacts (proposal.md, specs/, design.md, tasks.md) are this skill's core deliverables, landed through the normal archive flow — not subject to learn-and-improve's sediment-value gate. AI engineering knowledge (AGENTS.md, CLAUDE.md, .cursor/rules/, project-local skills, etc.) has its sediment-value judgment and carrier selection owned by learn-and-improve's decision tree; writing requires an explicit user request first.

Output format after archiving: see reference.md「Stage 8 Review & Archive」.

If archiving isn't appropriate, keep the change active and state the blockers and next steps.

Common mistakes

Only non-obvious pitfalls specific to this skill are listed here. Merge/coverage/tip pinning → merge-discipline; project-root/openspec//native-skill gates → opsx-workspace-gate. Rules already stated in the stage body are not repeated.

Mistake	Consequence	Fix
Creating the change before manual-mode confirmation	Breaks the stage-1 gate, may create the wrong directory	Stage 0 only prepares a candidate name; create it only after confirmation
Creating the proposal right after root-cause analysis (solution not yet chosen)	Why/What are disconnected, the artifact needs a rewrite	Create the proposal only after stage 3 picks a solution, in one pass via openspec-continue-change
Treating an old/short name as passing the gate (e.g. openspec-propose, openspec-apply)	Hand-written against a stale schema, or its SKILL.md can't be found	Accept only the exact four names: openspec-new-change / openspec-continue-change / openspec-apply-change / openspec-archive-change (verify is optional)
MODIFIED writing only a fragment	The archived requirement loses its original content	Copy the full requirement block, then edit
Running the coverage gate when branch closeout picked "keep / continue development"	Wrongly triggers the gate on a non-merge decision	The gate only fires on a "merge" decision
Running the analyzer by default under ask or when unconfigured	Forces a project with no coverage need through the gate	See merge-discipline Part C: resolve the preference first — ask must ask
Batching tasks.md checkbox updates until a group of tasks finishes	The verifier reports a CRITICAL false-incomplete	Flip the corresponding [ ] to [x] the moment each item finishes
Writing "a scenario was designed" as "verification passed"	The user accepts a false pass	Label each item "executed (command + output summary)" or "pending (action needed)"
A delta requirement without SHALL/MUST or without a Scenario	openspec validate keeps failing	Use SHALL/MUST in the description; add a #### Scenario:
Browser assertions based on assumed DOM instead of observed state	waitForFunction times out	Read the real value via evaluate before asserting

Minimum success criteria

A complete run must produce or update at least:

• openspec/changes/<change-name>/proposal.md
• openspec/changes/<change-name>/specs/<capability>/spec.md
• openspec/changes/<change-name>/design.md
• openspec/changes/<change-name>/tasks.md

On completion:

• All tasks are checked off.
• test-suite-ensure has run: unit tests all pass; E2E tests pass or a skip reason is stated.
• OpenSpec validation passes.
• Project verification passes, or manual-verification items are explicitly listed.
• Archived after user confirmation, or the change is kept active with the reason for not archiving stated.