Opsx Solve Workflow

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; ai-proxy 模式, AI 代理模式, 切换 ai-proxy
• Mode: overlay triggers (「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy") request overlay per workflow-mode-lifecycle (overlay+freeze wins if an auto trigger is also present). Else 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.

Unattended proxy exits: when this-run contract or task card records Stage-exit policy: ai-proxy (auto carrier; queue child is sufficient but not required), each manual exit above becomes a proxy checkpoint per ai-proxy-discipline. Thin freeze (verbal trigger ≠ occupancy) lives there. The pre-execution approval point takes the proxy's bounded pre-authorization instead of the bare auto escape of design-approval-gate; merge, irreversible, and protected-branch decisions stay human-only (park + ticket). Any other policy value or none → behavior identical to today.

Stop-point forecast: if this run starts with a frozen contract (queue child with problem + frozen decisions, or independent thin freeze already written), open with a forecast table before analysis — every manual exit × covered-by-frozen-decisions vs will-form-a-new-ticket. If overlay is requested mid-run, after thin freeze output a forecast of remaining exits, then continue the current stage (do not restart from analysis).

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 with runtime-evidence-debug as default entry / analysis step skeleton / analysis gate output block / 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)
• git-worktree-discipline (before stage 3 — first artifact write: worktree gate + 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)
• figma-pixel-implement / figma-pixel-verify (Figma export-faithful implement + measured verify; required installed; invoke only when Figma UI work is in scope)

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:

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

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.

Domain routing: if the problem is performance-domain (slow / jank / resource growth), suggest entering perf-optimize-workflow — its evidence-gated paradigm fits the domain; its analysis output can flow back into this workflow (artifacts still land in OpenSpec per this workflow). Note: its campaigns create per-project artifacts (benchmark log + harness, and seeded code-insight/code-optimizer skills); the optimize-verify loop additionally requires an environment loop runner — analysis stages always run. Informational reference, not a dependency.

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.

The stage output MUST close with the analysis gate output block (analysis-core §5 — red loop / debug entry / scenario supplements / temporary changes); a missing block blocks entry to Stage 3.

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.

Architecture-boundary precheck (decision order): when a candidate solution crosses process or layer boundaries, answer the precheck before short-term costs (change size / reuse / single-repo) are weighed — (1) runtime initialization location: which process/layer initializes the called capability; (2) boundary legality: would a cross-layer import pull the callee's dependency tree into the caller's bundle graph (bundler static pre-scanning defeats dynamic require/import as a workaround); (3) ownership classification: system vs data/product capability vs the calling layer's positioning. The boundary verdict surfaces with the comparison table and gates auto-mode selection. Methodology: code-design-review Layer A dependency-direction dimension. Single-layer solutions do not trigger this precheck.

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.

Before the first artifact write (proposal.md), load git-worktree-discipline (worktree gate + optional isolation).

🔌 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; blocking/non-blocking criteria are owned by solution-review and, for code solutions, code-design-review — a marginally better architecture with no material long-term maintainability gain does not block; a clearly superior feasible one does, per those skills):

• 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 + 留痕).

Figma pixel fidelity: When the task includes a Figma URL/node or pixel-restore / design-faithful UI intent, load figma-pixel-implement and follow it (export-faithful assets + design-spec table). Do not restate its methodology here.

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).
5. Figma pixel verify: when this run implemented from Figma or the user/plan requires alignment checking, load figma-pixel-verify and follow it for measured pass/fail (do not restate its methodology here).

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):

Verification execution follows runtime-verification-discipline (strong dependency): the AI executes verification itself in an environment, and hands a step to the user only at a classified true hard boundary, with the reason stated.

• AI can execute: use Bash to run test commands (e.g. npm test, pytest, go test) and fold the result into the check conclusion.
• Otherwise: classify the blocker per runtime-verification-discipline; only a true hard boundary becomes a user step, stated with its reason.

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.

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.