opsx-solve-workflow

OPSX 8 段階の問題解決ワークフロー

solve-workflow の 8 段階の PDCA 規律と、OpenSpec/OPSX のアーティファクト永続化を組み合わせます。目的は、AI が分析、提案、レビュー、検証を省略しないようにし、重要な結論がチャットのコンテキスト内だけに残らないようにすることです。

出力テンプレート：各段階の形式については、reference.md を参照してください。

位置付け

永続化する価値のあるエンジニアリング変更に、このスキルを使用します。要件、根本原因、動作の変更、技術的なトレードオフ、タスクリスト、検証結果をすべて openspec/changes/<change-name>/ に記録し、完了時にアーカイブを通じて openspec/specs/ にマージします。

役割分担：

• OpenSpec：信頼できる唯一の情報源およびアーカイブシステムです。「何を、なぜ行うか」に答えます。
• solve-workflow-style gates：段階のゲートです。「いつ次のステップに進めるか」に答えます。

通常の solve-workflow の代替ではありません：

• クイックフィックス、単一ファイルの軽微な編集、または長期的な追跡が不要なタスクには、solve-workflow を優先してください。
• 長期的な動作契約、チームレビュー、並行変更、要件監査、後日の追跡が関わるタスクには、このスキルを使用してください。

呼び出し規約

• トリガー：opsx解决, OpenSpec解决, 规范化解决, 创建OpenSpec变更, 创建opsx变更, 用OpenSpec分析, 用OpenSpec修复, opsx自动解决, OpenSpec自动解决, opsx-solve, opsx-solve-workflow; ai-proxy 模式, AI 代理模式, 切换 ai-proxy
• モード：オーバーレイのトリガー（「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy"）は、workflow-mode-lifecycle に従ってオーバーレイを要求します（自動トリガーも同時に存在する場合は、overlay+freeze が優先されます）。それ以外では、トリガーに「自动」（自動）が含まれる場合は自動モードに入り、そうでなければデフォルトで手動モードになります。
• 手動モード：段階 1、2、3、4、5、7、8 の主要な終了時には、ユーザーの確認を待つ必要があります。
• 自動モード：検証まで自動で進みます。段階 4 のレビューループは最大 3 ラウンドで、その後一時停止します。

無人プロキシ終了：この実行の契約またはタスクカードに Stage-exit policy: ai-proxy が記録されている場合（自動キャリア。キューの子タスクで十分ですが、必須ではありません）、上記の各手動終了は ai-proxy-discipline に従うプロキシチェックポイントになります。薄いフリーズ（言葉によるトリガー ≠ 占有）は、そちらに記載されています。実行前の承認ポイントでは、design-approval-gate における単純な自動実行の例外ではなく、プロキシの範囲を限定した事前承認を使用します。マージ、不可逆的な操作、保護ブランチに関する判断は引き続き人間のみが行います（保留してチケットを作成）。それ以外のポリシー値、または値がない場合の動作は、これまでと同じです。

停止ポイントの予測：この実行が、フリーズ済みの契約（問題とフリーズ済みの決定を含むキューの子タスク、またはすでに作成された独立した薄いフリーズ）で開始する場合は、分析の前に予測表を提示します。各手動終了について、フリーズ済みの決定で対応済みか、新しいチケットを作成するかを示します。実行の途中でオーバーレイが要求された場合は、薄いフリーズの後に、残りの終了ポイントの予測を出してから、現在の段階を続行します（分析からやり直さないでください）。 強い依存関係にあるスキル（frontmatter の dependencies に記載。起動時の「前提スキルチェック」に合格する必要があります。不足があれば中止します）：

• staged-review-flow（ステージ 4 のレビューオーケストレーション。solution-review と code-design-review に依存）
• hybrid-debug / runtime-evidence-debug / browser-debug-toolkit（analysis-core 経由で委譲。ステージ 2 とステージ 7）
• analysis-core（ステージ 2 の分析方法の単一の情報源。一時変更ゲート／デフォルトのエントリポイントとしての runtime-evidence-debug を使った計測デバッグ／分析手順の骨子／分析ゲートの出力ブロック／デバッグ・検証ループ）
• context-budget-discipline（ステージ 6／7 の開始時：フェーズ境界でのリセット評価、事前の圧縮しきい値、リセット前の台帳引き継ぎ）
• node-version-discipline（ステージ 7 の Node バージョン整合）
• learn-and-improve（ステージ 8 の振り返りとナレッジの蓄積）
• workflow-mode-lifecycle（自動／手動モードのライフサイクル）
• clarifying-question-discipline（質問を積極的に行うことと、調査を優先することに関する厳格な規律）
• known-issue-research（ステージ 2 の調査振り分け／既知の問題のクイック検索／業界全体の評価）
• competitive-research（分析中にユーザーから見える競合製品の動作。手法はこのスキルに従います）
• test-suite-ensure（ステージ 6 のテストスイート確保：インフラがあればテストを完了して実行し、なければユーザーの確認を得て足場を構築）
• test-first-discipline（ステージ 6：動作変更では失敗するテストを先に作成。test-suite-ensure とは別）
• design-approval-gate（ステージ 6 の前：承認なしで本番実装を行わない。指定された自動／ホットフィックスの例外あり）
• delivery-discipline（ステージ 8：アーカイブ後に任意でコミットし、PR／MR を作成または更新。すべての実行で成果物を届けるわけではありません）
• feature-branch-closeout（ステージ 8：アーカイブ後のクローズアウトメニュー。マージは merge-discipline に委譲）
• decision-fog-discipline（解決策の検討前：まず曖昧さを解消し、意思決定チケットを作成）
• git-worktree-discipline（ステージ 3 の前、最初の成果物を書き込む前：ワークツリーゲートと任意の分離ワークスペース）
• domain-language-discipline（明確化／分析時：ドメイン用語が重要な場合のプロジェクト用語集／CONTEXT.md）
• merge-discipline（ステージ 8 のマージ規律。クローズアウトでマージを選択した後）
• opsx-workspace-gate（ステージ 0 の OpenSpec ワークスペースおよびネイティブスキルのゲート）
• figma-pixel-implement / figma-pixel-verify（Figma のエクスポートに忠実な実装と、計測に基づく検証。インストール必須。目標、カード、課題、計画に figma.com または node-id= が含まれる場合、あるいはユーザーがピクセル単位での復元を依頼した場合に呼び出します）

前提スキルチェック

起動時（ステージ 0 のゲート通過後、ステージ 1 の前）に、frontmatter の dependencies を確認します。利用可能なスキルを調べ、不足があれば、構造化されたプロンプトを表示して直ちに中止します（形式は solve-workflow/reference.md「Prerequisite Skill Check — Missing Notice」を参照）。

品質を低下させない原則：強い依存関係にあるスキルが不足している場合は中止します。簡略化したレビューやデバッグフローに切り替えて続行してはいけません。

モードのライフサイクル

自動モードの開始、継続、終了に関するルールです。AI が引き続き自動で判断していることにユーザーが気づかないまま、モードが固定されるのを防ぎます。中核となるルール（手動モードへの復帰／明示的な再開／暗黙の継続では再有効化しない／バッチ処理のシナリオ）は、強い依存関係にあるスキル workflow-mode-lifecycle（前提スキルチェックにより利用可能であることが保証されています）に記載されており、ここでは繰り返しません。

OpenSpec 固有の注意事項

• ステージ 8 のアーカイブが完了した後、モードは自動的に手動モードに戻ります。
• ユーザーが次の PDCA サイクル（ステージ 3／4／5 に戻る）を開始する場合、デフォルトで手動モードになります。
• アーカイブの中断（例：openspec-archive-change スキルの失敗）もフローの中断として扱い、手動モードに戻します。

---

ステージ 0：環境の確認とパスの選択

このスキルには、完全に初期化された OpenSpec ワークスペースが必要です。簡易的な代替手順はありません。opsx-workspace-gate を読み込み、プロジェクトルートの特定、openspec/ の確認、ネイティブ OPSX スキルの厳密なゲートを実行します。ゲートを通過したら、このワークフロー独自のステージゲートと後続のオーケストレーションに従います。

ゲート通過後の準備手順

1. 既存の変更を使用するか、新しい変更を作成するかを決め、候補名のみを準備します。
   • ユーザーが変更名を指定した場合は、それを優先して使用します。
   • それ以外の場合は、新しい作業用のケバブケースの候補名を生成し、手動モードではユーザーに確認します。
2. 作成方法を準備しますが、ステージ 1 でユーザーの確認を得る前にディレクトリを作成してはいけません。openspec-new-change スキルを使用して変更を作成します（SKILL.md を読み、その指示に従います）。

パスの選択

タスクに応じてパスを選び、続行する前に宣言します。

パス	適したケース	要件
フル	まったく新しい機能、複雑なモジュール、要件が曖昧な場合	ステージ 1～8 をすべて実行
インクリメンタル	既存の動作変更、リファクタリング、一般的なバグ	ステージ 1～8 を実行。ただし、提案や仕様は簡潔にしてもよい
リーン	ホットフィックス、影響範囲が小さく確実性の高い変更	提案、差分仕様、タスク、検証、アーカイブを実施し、検証を省略しない

実行中にスコープが拡大した場合は、パスをアップグレードする必要があります。リーン → インクリメンタル、インクリメンタル → フルの順です。手動モードでは、アップグレードにユーザーの確認が必要です。

ステージと成果物の対応

ステージ	目標	OpenSpec の保存先	コードへの書き込み
1. 問題を明確にする	問題について認識を合わせ、要素を抽出し、未解決の質問を解決する	分析のみ。成果物なし	禁止
2. 問題を分析する	問題の存在を確認し、根本原因を特定し、影響を評価する	分析のみ。成果物なし（結論はステージ 3 の後に proposal.md に記載）	禁止
3. 解決策を検討する	2～5 個の解決策を提示し、1 つを選ぶ	openspec-continue-change 経由で proposal.md（完成版）+ specs/<capability>/spec.md（差分仕様）	禁止
4. 解決策をレビューする	妥当性、リスク、実現可能性をレビューする	openspec-continue-change 経由で design.md	禁止
5. 計画を立てる	実行可能なタスクに分解する	openspec-continue-change 経由で tasks.md	禁止
6. 計画を実行する	タスクごとに実装し、完了を記録する。すべてのタスクが完了したら、テストスイートが整っていることを確認するため test-suite-ensure を呼び出す	openspec-apply-change 経由で tasks.md のチェックボックスを更新。テストファイル（test-suite-ensure によって生成）	許可
7. 確認と検証を行う	テスト、検証、成果物との照合を行う	openspec-verify-change スキルまたは openspec validate による検証結果	禁止
8. レビューしてアーカイブする	結果を反映するか、次のラウンドを開始する	openspec-archive-change スキル経由で openspec/specs/ を更新し、openspec/changes/archive/ に移動	アーカイブ／ドキュメントのみ

ステージ 1～5 では、業務コードの変更は禁止されていますが、OpenSpec の成果物の作成と更新は許可されています。ユーザーが「分析だけして、保存しないで」と依頼した場合は、ステージの結論のみを出力し、成果物の書き込みは省略します。

ステージ 1：問題を明確にする

⚠️ 積極的な質問：clarifying-question-discipline に従ってください（1 回につき質問は 1 つ。明確になるまで複数回にわたり、急いで回答せず、まず確認します）。ドメイン固有の用語が使われている場合は、domain-language-discipline にも従ってください。

ドメインの振り分け：問題がパフォーマンス領域（遅い／カクつく／リソースの増加）に関する場合は、perf-optimize-workflow の利用を提案してください。その根拠に基づくゲート方式はこの領域に適しており、分析結果をこのワークフローに引き継げます（成果物はこのワークフローに従って引き続き OpenSpec に保存されます）。注：このワークフローのキャンペーンでは、プロジェクトごとの成果物（ベンチマークログとハーネス、およびシード済みの code-insight／code-optimizer スキル）が作成されます。最適化と検証のループには、さらに環境ループランナーが必要ですが、分析ステージは常に実行されます。これは参考情報であり、依存関係ではありません。

手動モードでは、次の手順を順番に完了する必要があります。

1. 問題を言い換える — ユーザーの問題を自分の言葉で説明します。
2. 重要な要素を抽出する — 目標、制約、背景、期待される結果を整理します。
3. 未解決の質問を列挙する — さらに確認が必要な点を列挙します。ユーザーに質問する場合は、一度に最も重要な質問を 1 つだけ尋ね、回答を得てから次の質問をしてください。 3.5. スコープを分解する（該当する場合）— 問題が複数の独立したサブシステムにまたがる場合は、まず分解を支援します。独立したモジュール、依存関係、推奨される対応順を整理してから、最初のサブ問題についてステージ 2 の技術分析に進みます。
4. ユーザーの確認を待つ。

ツールの制限：Read／Grep／SemanticSearch の使用は禁止されています。ただし、次の場合は例外です。

• ユーザーのメッセージに @file-path（行番号は任意）が含まれている
• ユーザーがコードスニペットを貼り付けている
• ユーザーが「関数名／クラス名＋そのファイル」の組み合わせを明示している

例外に該当する場合は、ユーザーが直接指定したファイルと行のみを読み取り、ほかのファイルには範囲を広げないでください。読み取り結果は問題の理解にのみ役立ててください。ステージ 1 の出力に技術分析の結論を含めてはいけません。

手動モードの出力形式については、reference.md の「ステージ 1：問題を明確にする」を参照してください。

ユーザーの確認前に変更を作成したり、ファイルを変更したりしないでください。確認後は、次の手順に従います。

1. openspec-new-change スキルを使用して変更ディレクトリを作成します（SKILL.md を読み、その指示に従います）。
2. 今回の進め方（full／incremental／lean）を記録します。
3. その後、ステージ 2 の技術分析に進みます。

自動モードでは確認を省略できますが、まず候補名を生成してから、すぐに変更を作成し、作業を続ける必要があります。

ステージ 2：問題を分析する

分析方法の唯一の情報源は analysis-core です。このステージでは実装上の変更は行いません。修正はステージ 6 で行います。

analysis-core に委任する

強い依存関係である analysis-core を読み込み、その §§1-3 を実行します。このワークフローにおける対応関係は次のとおりです（番号＋名前）。

• {next-stage} = ステージ 3「解決策を検討する」
• {root-cause step} = ステップ 5、{impact-assessment step} = ステップ 7、{upstream-eval step} = ステップ 6

🔌 OPSX：このステージでは成果物を作成しません。Why／Impact は、ステージ 3 で解決策を選択した後に proposal.md に記録します。

ステージの出力は、分析ゲートの出力ブロック（analysis-core §5 — red loop／デバッグ開始／シナリオ補足／一時的な変更）で必ず締めくくってください。このブロックがない場合は、ステージ 3 に進めません。期待される結果が、ユーザーが確認または操作できるものである場合、同じ読み込みで analysis-core に従って competitive-research も実行します。その手法を改めて説明する必要はありません。

存在確認に失敗した場合、または説明とコードが一致しない場合は、ユーザーの確認を求め、解決策の検討には進まないでください。

---

ステージ 3：解決策の検討

原則：ステージ 2 の分析に基づいて、2〜5 個の解決策を提示します。YAGNI に従い、すべての解決策から不可欠でない機能や過剰な設計を取り除いてください。方針がまだ不明瞭な場合は、解決策の表／提案を作成する前に decision-fog-discipline に従ってください。

アーキテクチャ境界の事前確認（判断の順序）：候補となる解決策がプロセスまたはレイヤーの境界をまたぐ場合、短期的なコスト（変更規模／再利用／単一リポジトリ）を検討する前に、次の事前確認に回答してください。（1）ランタイムの初期化場所：呼び出される機能を初期化するプロセス／レイヤーはどれか。（2）境界の適法性：レイヤーをまたぐインポートによって、呼び出し先の依存関係ツリーが呼び出し元のバンドラーグラフに取り込まれるか（バンドラーによる静的な事前スキャンにより、動的な require／import を回避策として使えなくなります）。（3）所有権の分類：システム機能か、データ／プロダクト機能か、または呼び出し元レイヤーの位置付けか。境界に関する判断は比較表に反映し、自動モードの選択条件となります。方法論については、code-design-review の Layer A の依存方向の観点を参照してください。単一レイヤーの解決策では、この事前確認は不要です。

ステージ 2 に基づいて 2〜5 個の解決策を作成し、それぞれに以下を含めてください。

• 中核となる考え方
• 関連する機能または動作の変更
• 追加または変更する OpenSpec の機能
• メリット、デメリット、複雑さ、リスク
• 推奨する解決策

手動モードでは、比較表を出力した後、ユーザーが選択するまで待ちます。

最初の成果物（proposal.md）を書き込む前に、git-worktree-discipline を読み込みます（ワークツリーの確認ゲート＋任意の分離）。

🔌 OPSX スキルの統合：解決策を選択したら、openspec-continue-change スキルを使って次の 2 つの手順を完了します（呼び出し 1 回につき成果物を 1 つ作成します。まず SKILL.md を読み、その指示に従ってください）。

1. proposal.md を作成する（変更における最初の準備完了成果物）：ステージ 2 の根本原因分析（Why / Impact）と、このステージで選択した解決策（What Changes / Capabilities）を統合し、完全な提案を作成します。
2. 差分仕様を作成する（提案が完成すると仕様の準備が整います）：動作の変更を specs/<capability>/spec.md に記述します。

差分仕様の規約（openspec-continue-change スキルで適用）：

• 動作の変更のみを記述します：## ADDED、## MODIFIED、## REMOVED、## RENAMED Requirements
• すべての要件見出しは ### Requirement: <SHALL または MUST を含む説明> とします。
• すべての要件に、少なくとも 1 つの #### Scenario: ブロックを含めます。

よくある誤り：### REQ-001:（形式が誤っています）、### Requirement: Initialize（SHALL／MUST がありません）、Scenario ブロックがない。 3 つとも openspec validate に失敗します。形式の例は openspec-continue-change スキルにあります。

危険信号 — ステージ 3 で禁止されていること

• 「方針はすでに明確」という理由で、解決策を 1 つだけ生成し、比較を省略すること
• 手動モードで、ユーザーが解決策を選ぶ前にレビューへ進むこと
• 不可欠でない機能や過剰な設計を含む解決策（YAGNI 違反）

ステージ 4：解決策をレビューする

staged-review-flow を読み込み、そのレビュー契約全体を実行します。このワークフローでは、対応関係を次のように設定します。{next-stage} = ステージ 5「計画を立てる」；{artifact-sink} = openspec-continue-change で作成する design.md；{extra-dimensions} = 仕様への準拠（提案の why、差分仕様の動作、設計のリスク、要件に対するタスクの網羅性）；{batch-overcap-behavior} = N/A。レビューに合格したら、ネイティブスキルを使って design.md を作成します。

ブロック対象外の問題（提案として指摘してもかまいませんが、合格を妨げることはありません。ブロック対象かどうかの基準は solution-review が定め、コードの解決策については code-design-review も定めます。長期的な保守性に実質的な向上をもたらさない、わずかに優れたアーキテクチャはブロック対象になりません。一方、明らかに優れた実現可能なアーキテクチャは、これらのスキルに従ってブロック対象となります）：

• 既存の緩和策がある低リスクの項目
• 正確性や構造に影響しないコードスタイル上の好み
• 後のイテレーションに先送りできる、構造に関わらないパフォーマンス改善
• 返済計画が明示され、明示的に受け入れられた Prudent-Deliberate の技術的負債

レッドフラグ — ステージ 4 で禁止

• 解決策のレビューを省略して、そのままステージ 5 に進む（リスクが特定されないため）
• レビュー段階でコードを変更する（読み取り専用の制約に違反するため）
• 自動モードのレビューで不合格になった際に解決策を最適化せず、そのままステージ 5 に進む
• 自動モードのレビューを上限の 3 ラウンドを超えて続け、中断しない
• レビューの追跡可能性を損なうような、最適化の根拠を記録しないまま自動モードで解決策を最適化する
• 手動モードで、ユーザーから明示的な合否判定を受けていないのに AI が独自に先へ進む

ステージ 5：計画を立てる

🔌 OPSX スキル連携：openspec-continue-change スキルを使って tasks.md を生成します（先に SKILL.md を読み、その指示に従ってください。仕様と設計の両方が完了すると、タスクの作成が可能になります）。このスキルは tasks.md の内容を直接手書きすることはありません。

tasks.md の規約（スキルによって適用されます）：

• チェックボックスを使い、タスクは十分に細分化し、依存関係が反映される順序にします
• 必要なテスト、検証、ドキュメント作成、移行の手順を含めます
• TBD、TODO、「適切に処理する」、「上記と同様」、その他の実行可能でない説明は使用しません

手動モードでは、計画を出力して一時停止します。ステージ 6 に入る前に、ユーザーの確認を待ちます。

ステージ 6：計画を実行する

本番コードを編集する前に、design-approval-gate に従ってください（manual：ユーザー承認、auto/lean：名前付きの例外処理＋記録）。

コンテキスト予算：context-budget-discipline に従い、フェーズ境界でのリセットとコンパクションのしきい値を評価してください（台帳のパスはステージ 5 の計画を参照）。リセットが必要な場合は、まず完全な台帳エントリを記録してください。

**Figma のピクセル忠実度：**ゴール、カード、Issue、または計画のテキストに figma.com または node-id= が含まれている場合、あるいはユーザーがピクセル単位の復元（像素级还原）を求めている場合は、figma-pixel-implement を読み込み、その指示に従ってください。その部分文字列が対象範囲を決める事実です。タスクで動作も確認する場合でも、該当する行はハードのままにし、ソフトや人間の確認項目に移さないでください。表示テキストの確認、表示フラグ、リストの長さだけでは、ピクセル関連の行を満たしたことにはなりません。同じテキストに 参考、match the existing、または same as も含まれている場合は、その事実を verify に渡し、指定されたコントロールの操作状態を行として確認してください。対象リポジトリ内に永続的なインベントリ＋仕様書のパスがなければ、実装は完了していません。このスキルは、全体が PASS になるか、計測コマンドを実行できなくなるまで、同じ実行中に figma-pixel-verify へ引き継がれます。ここでその手法を繰り返し説明しないでください。

tasks.md を読み、次の順序で実装してください。

1. 一度に取り組むのは、現在の最小のタスク 1 つだけにしてください。
2. 業務コードに触れる前に、関連する提案、仕様、設計、タスクがすでに存在することを確認してください。
3. タスクを終えたら、直ちにチェックボックスを更新してください：tasks.md 内の該当する [ ] を [x] にするために StrReplace を使用してください。複数のタスクをまとめて完了してから更新してはいけません。これを省略すると、ステージ 7 の検証で CRITICAL の誤った未完了判定が報告されます。
4. 実装によって設計または仕様が不正確だと判明した場合は、実装を続ける前に該当する成果物を更新してください。
5. 計画から逸脱する場合は、その理由を明示してください。逸脱がスコープまたは動作上の契約に影響する場合は、ステージ 4 またはステージ 5 に戻ってください。

まずテストを実施し、その後テストスイートを確保する（必須、実行報告の前）

動作を変更する作業では、test-first-discipline に従ってください（本番コードより前に、テストが失敗することを確認します）。tasks.md のチェックボックスをすべてチェックしたら、実行報告を出力する前に、以下の手順が必須です。

test-suite-ensure を読み込み、mode=mandatory を指定して、この変更のロジックファイルを対象に呼び出してください。失敗した場合、または必要な足場の追加依頼を断った場合は、ステージ 7 に進めません。test-suite-ensure は test-first の代わりにはなりません。

🔌 OPSX スキル連携：タスクを実行するために openspec-apply-change スキルを呼び出してください（まず SKILL.md を読み、その指示に従って各タスクを完了してください）。openspec-apply-change は CLI を内部的に使用して変更ステータスと実行手順を取得します。このスキルから実行を進めるために CLI を直接呼び出すことはありません。

ステージ 7：確認と検証

コンテキスト予算：リセットが発生した場合は、台帳と成果物に照らして検証します（context-budget-discipline に従います）。前のセッションの履歴を再生してはいけません。

検証では、次の 3 つの層を確認します。

1. OpenSpec の検証：
   • openspec-verify-change スキルが検出された場合 → その SKILL.md を読み、検証を委任します。
   • 存在しない場合 → openspec validate <change-name> または openspec validate --changes を直接実行します（CLI ツールの呼び出しであり、機能を縮小する対応ではありません）。

Node バージョンの整合（前提条件）：以下のエンジニアリング検証コマンドを実行する前に、node-version-discipline を呼び出して、プロジェクトで宣言されている Node バージョンに合わせます。

2. エンジニアリング検証：整合させたバージョンで、プロジェクトのテスト、型チェック、リント、またはビルドを実行します。
3. 動作の照合：delta spec の要件とシナリオをすべて実装が満たしていることを、1 つずつ確認します。
4. デバッグ・検証ループ：ステージ 2 で根本原因の特定にデバッグスキルを使用した場合は、analysis-core §4 に従い、テストだけでなく、同じスキルを使って修正を検証します。
5. Figma のピクセル検証：ゴール、カード、イシュー、または計画に figma.com または node-id= が含まれている場合、あるいは今回の実行で Figma をもとに実装した場合は、figma-pixel-verify を読み込んでその手順に従います。計測レポート（継続して更新される成果物の Verify セクション、または Spec のソースと同じ階層にあるレポート）がない場合、この検証ステージは合格になりません。Spec の不足による FAIL は検証合格になりません。テーブルを完成させるため、figma-pixel-implement に戻ってください。同じ実行内で実装していない場合でも、ユーザーまたは計画で整合性の確認が求められていれば、検証を読み込みます。このステージに合格するのは、レポートの全体ステータスが PASS（受け入れ済みの残差を含む）で、かつチャンネルがレイアウト済みの計測（storybook、isolated-harness、preview、full-app、または layout-probe）の場合に限ります。それ以外の結果はこのステージで不合格となり、修正と再計測のループのため実装ステージに戻ります。このステージでは、figma-pixel-verify スキルの scripts/check-figma-verify-report.mjs もそのレポートに対して実行します。終了コードが 0 以外の場合、ステージは不合格です。検証の方法論を言い換えて説明してはいけません。

検証の結論は、このラウンドで実行し、出力を自分で確認したコマンドに基づかなければなりません。「シナリオを設計した」ことを「合格」と報告してはいけません。

今回のターンのディスパッチに、凍結されたタスクカードがインラインで含まれる場合、検証レポートには問題、原因、完了した修正、およびエビデンスの一覧を記載します。各エビデンス項目は、png、jpg、jpeg、または webp のパスを示す UI の確認、またはコマンドと短い出力の要約を示す非 UI の確認です。画像がない、または空の場合は保留とし、撮影がまだ必要であると記載します。画像を捏造してはいけません。UI を開いたときの画像を確認の根拠として使う前に、completion-evidence-discipline に従って画像を確認します。この実行では HTML ページもエビデンス HTML も作成しません。

出力形式：reference.md「Stage 7 Check & Verify」を参照してください。

staged-review-flow の検証レポートにおける誠実性ルールと completion-evidence-discipline に従って、各結果にラベルを付けます（今回のターンで新たに取得したエビデンスなしに合格を主張してはいけません）。

手動モードでは、アーカイブ前にここで停止し、ユーザーの確認を待ちます。検証が不合格の場合はアーカイブせず、ステージ 4、5、または 6 に戻ります。

テストの実行

ステージ 6 の実行レポートにテスト（ユニットテスト、統合テスト、手動検証の手順）が含まれる場合：

検証の実行には runtime-verification-discipline を適用します（強い依存関係）。AI は環境内で自ら検証を実行し、分類された真のハード境界に限り、理由を明示したうえで手順をユーザーに引き継ぎます。

• AI が実行できる場合：Bash を使ってテストコマンド（例：npm test、pytest、go test）を実行し、結果を確認の結論に反映します。
• それ以外の場合：runtime-verification-discipline に従ってブロッカーを分類し、真のハード境界のみを、理由を明記してユーザーの手順とします。

Stage 8: レビューとアーカイブ

検証に合格した場合は、アーカイブ前のチェックを実行します。

• tasks.md の項目はすべて完了していますか？
• 差分仕様は実際の実装を反映していますか？
• メイン仕様は正しく更新されますか？
• ユーザーはアーカイブを確認しましたか？

🔌 OPSX スキルの統合：アーカイブする前に、次の手順を実行します。

1. 差分仕様がある場合：openspec-sync-specs スキルがインストールされていれば呼び出し、差分仕様をメインの specs/<capability>/spec.md に統合します。または、アーカイブ中に openspec-archive-change に同期を促して処理させます。
2. アーカイブを実行する：openspec-archive-change スキルを呼び出します（最初に SKILL.md を読み、その指示に従います）。

openspec-archive-change が失敗した場合は、openspec/ ディレクトリを手動で操作してはいけません。停止し、OpenSpec のインストールを確認するようユーザーに伝えてください。

アーカイブ後は、必ず差分を確認し、メイン仕様の更新とアーカイブディレクトリの移動の両方がプロジェクトルートの Git 作業ツリーの変更に反映されていることを確認します。その後、この実行でコミットと PR/MR が必要になる可能性がある場合は delivery-discipline を読み込みます（アーカイブの差分では通常、デリバリーが必要ですが、スキルの必要性判定でスキップされることがあります）。続いて、クローズアウトメニュー（PR／マージ／保持／続行）のために feature-branch-closeout を読み込みます。テストに合格していない、アーカイブが完了していない、または差分をレビューしていない場合は、完了を宣言してはいけません。

順序の制約：アーカイブと差分チェック → 任意で delivery-discipline → feature-branch-closeout → マージ時は merge-discipline の A→B→C→R→D。保持／続行を選んだ場合、マージ規律は適用されません。

マージ規律（merge-discipline スキル）

マージ時（クローズアウトでのマージ、またはユーザーによる直接のマージコマンド）は、merge-discipline を読み込み、Part A → B → C → R → D を実行します。マージ前チェックリストは merge-discipline/reference.md にあります。暗黙的にスキップしてはいけません。

振り返り（learn-and-improve に委任）

アーカイブとブランチのクローズアウトが完了したら、learn-and-improve を読み込み、そのフレームワークに従います。通常のフローでアーカイブされた OpenSpec アーティファクトは、その沈殿価値ゲートの対象外です。

OpenSpec アーティファクト（proposal.md、specs/、design.md、tasks.md）は、このスキルの中核となる成果物であり、通常のアーカイブフローを通じて取り込まれます。learn-and-improve の沈殿価値ゲートの対象外です。 AI エンジニアリングの知識（AGENTS.md、CLAUDE.md、.cursor/rules/、プロジェクト固有のスキルなど）は、learn-and-improve の判断ツリーが沈殿価値の判断と格納先の選択を担います。明示的なユーザーの依頼がない限り、書き込みは禁止です。

アーカイブ後の出力形式については、reference.md「Stage 8 Review & Archive」を参照してください。

アーカイブが適切でない場合は、変更をアクティブな状態に保ち、阻害要因と次の手順を明示してください。

よくある間違い

ここでは、このスキル特有の、見落としやすい落とし穴のみを挙げます。マージ／カバレッジ／チップのピン留め → merge-discipline、プロジェクトルート／openspec/／ネイティブスキルのゲート → opsx-workspace-gate を参照してください。ステージ本文ですでに説明されているルールは繰り返しません。

間違い	結果	修正方法
手動モードの確認前に変更を作成する	ステージ1のゲートに違反し、誤ったディレクトリを作成する可能性があります	ステージ0では候補名の準備のみを行い、確認後に作成します
根本原因の分析直後に提案を作成する（解決策がまだ決まっていない）	Why と What が結び付かず、成果物を書き直す必要が生じます	ステージ3で解決策を選んだ後に限り、openspec-continue-change を使って一度に提案を作成します
古い名前や短縮名をゲート通過として扱う（例：openspec-propose、openspec-apply）	古いスキーマに基づいて手作業で作成されるか、SKILL.md が見つかりません	次の4つの名前との完全一致のみを受け入れます：openspec-new-change ／ openspec-continue-change ／ openspec-apply-change ／ openspec-archive-change（verify は任意）
MODIFIED で一部だけを書く	アーカイブされた要件から元の内容が失われます	要件ブロック全体をコピーしてから編集します
ブランチのクローズアウトで「keep / continue development」が選ばれたときにカバレッジゲートを実行する	マージしない判断に対して誤ってゲートを実行します	ゲートが起動するのは「merge」の判断がされた場合のみです
ask の設定時、または設定がない場合に、アナライザーをデフォルトで実行する	カバレッジが不要なプロジェクトにもゲートを強制します	merge-discipline の Part C を参照し、まず設定を確認します。ask の場合は質問が必要です
タスクのグループが終わるまで tasks.md のチェックボックス更新をまとめて行う	検証ツールが CRITICAL の誤った未完了判定を報告します	各項目が完了した時点で、対応する [ ] を [x] に変更します
「シナリオを設計した」を「検証に合格した」として記述する	ユーザーに誤った合格判定を受け入れさせてしまいます	各項目に「実行済み（コマンド＋出力の要約）」または「保留中（必要なアクション）」と明記します
SHALL／MUST がない、または Scenario がない差分要件	openspec validate が失敗し続けます	説明に SHALL／MUST を使用し、#### Scenario: を追加します
実際に観察した状態ではなく、想定した DOM に基づいてブラウザーのアサーションを行う	waitForFunction がタイムアウトします	アサーションの前に evaluate で実際の値を読み取ります

最低限の成功基準

一連の作業を完了するには、少なくとも次のファイルを作成または更新する必要があります。

• 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

完了時には、次を満たしている必要があります。

• すべてのタスクにチェックが付いています。
• test-suite-ensure が実行済みです。ユニットテストはすべて合格し、E2E テストは合格しているか、スキップ理由が明記されています。
• OpenSpec の検証に合格しています。
• プロジェクトの検証に合格しているか、手動検証が必要な項目が明示されています。
• ユーザーの確認後にアーカイブされているか、アーカイブしない理由を明記したうえで変更がアクティブな状態に保たれています。