opsx-jira-fix-workflow

OPSX Jira バグ修正ワークフロー

Jira の修正に OpenSpec の要素を取り入れたバージョンです。jira-fix-workflow のエンドツーエンドの修正機能を維持しながら、OpenSpec を動作上の真実のソースとします。

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

位置づけ

このスキルは、記録に残す価値がある Jira のバグ修正に使用します。コードを修正するだけでなく、根本原因、動作の変更、設計上のトレードオフ、タスクリスト、検証の証跡、アーカイブ結果も記録します。

役割分担：

• Jira：問題の発生元、ビジネスコンテキスト、ステータスの遷移、修正コメント。
• openspec/changes/<change-name>/：Jira のコンテキスト、根本原因、動作上の契約、解決策、タスク、検証、最終アーカイブ。
• PR/MR：コードの提供、検証の証跡、リスクに関する注記、レビューの起点。

通常の jira-fix-workflow の代替ではありません。

• 長期的な追跡の必要がない迅速な修正には、jira-fix-workflow を使用してください。
• 動作上の契約、監査、チームでのコラボレーション、モジュール間への影響、長期的な追跡には、このスキルを使用してください。

呼び出し規約

• トリガー: opsx-jira-fix、OpenSpec Jira 修复、规范化修复 Jira、opsx修复Jira、Jira OpenSpec 修复、opsx自动修复Jira、用OpenSpec修复Jira、opsx-jira-fix-workflow；ai-proxy 模式、AI 代理模式、切换 ai-proxy
• オーバーレイ: 「ai-proxy 模式」「AI 代理模式」「切换 ai-proxy」 / "ai-proxy mode" / "switch to ai-proxy" のリクエストでは、workflow-mode-lifecycle に従ってオーバーレイを適用します（自動トリガーも含まれる場合は、オーバーレイ＋凍結が優先されます）。ai-proxy-discipline に従って、薄く凍結してから占有します。
• 自動モード: それ以外の場合、「自动」を含むトリガー、または --auto がある場合は自動モードに入ります。
• 強制モード: 「强制」を含むトリガー、または --force がある場合は、難易度に基づく停止を省略できますが、検証やアーカイブの確認は省略できません。
• 修復の続行: 「继续修复」「再次修复」「从上次继续」を含むトリガー、または --retry がある場合は、まず既存の OpenSpec 変更を特定し、次に design.md、tasks.md のチェックボックス、現在の Git ブランチ、PR/MR のステータスからコンテキストを復元します。

強い依存関係を持つスキル（フロントマターの 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 をデフォルトのエントリーポイントとする／分析ステップの骨格／分析ゲートの出力ブロック／デバッグ検証ループ）
• node-version-discipline（ステージ 6 の実行検証前に Node のバージョンを合わせます）
• workflow-mode-lifecycle（自動／手動モードのライフサイクル）、clarifying-question-discipline（厳格な質問規律と調査優先）、known-issue-research（ステージ 2 の調査ルーティング／既知の問題のクイック検索／業界全体の評価）、competitive-research（分析時のユーザーに見える競合の挙動。手法はこのスキル内に維持）
• test-suite-ensure（ステージ 6.2.5 のテストスイート整備。インフラがある場合はテストを補完して実行し、ない場合はユーザーの確認を得てひな形を作成）
• test-first-discipline（実行：動作変更では失敗するテストを先に作成。test-suite-ensure とは別）
• design-approval-gate（実行前：承認なしで本番実装を行わない。明示された自動／ホットフィックスの例外あり）
• delivery-discipline（ステージ 8：アーカイブ後にコミットし、PR/MR を開く／更新する。フィールドマップはプレースホルダー経由）
• feature-branch-closeout（ステージ 8：クローズアウトの選択肢。マージは merge-discipline に委任）
• decision-fog-discipline（解決策を検討する前に、曖昧さを解消する／判断チケットを先に作成する）
• git-worktree-discipline（ステージ 1 の前、最初の成果物を書き込む前：worktree ゲートと任意の隔離ワークスペース）
• domain-language-discipline（ドメイン用語が重要な場合の明確化／分析：プロジェクト用語集／CONTEXT.md）
• merge-discipline（ステージ 8 のマージ規律。クローズアウトでマージが選択された後）
• opsx-workspace-gate（ステージ 0 の OpenSpec ワークスペースとネイティブスキルのゲート）
• jira-status-writeback（ステージ 8 のマージ後の書き戻し：ステータス遷移と修正コメントの SOP。単一の情報源）
• jira-wiki-markup（すべての Jira コメント本文で使用する Wiki マークアップ。書き戻し時に修正コメント用として読み込みます）
• learn-and-improve（ステージ 8 の振り返りと知識の蓄積）
• figma-pixel-implement / figma-pixel-verify（Figma エクスポートに忠実な実装と計測による検証。インストール必須。目標、カード、課題、計画に figma.com または node-id= が含まれる場合、あるいはユーザーがピクセル単位の復元を求めた場合に呼び出します）

前提スキルの確認

起動時（ステージ 0 の前提条件チェックの前）に、フロントマターの dependencies を確認します。不足がある場合は、構造化されたプロンプトを出力し、ただちに中断します（形式：solve-workflow/reference.md）。

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

モードのライフサイクル

自動モードの開始、継続、終了のルールです。ユーザーが AI による自動判断が続いていることに気づかないまま、モードが固定化するのを防ぎます。中核となるルール（手動モードへの復帰／明示的な再開始／暗黙の継続では再有効化しない／バッチシナリオ）は、強い依存関係にあるスキル workflow-mode-lifecycle（前提条件のチェックによりすでに利用可能であることが保証されています）に記載されているため、ここでは再掲しません。このワークフローにおける「フロー全体の完了」とは、ステージ 0～8 を通常どおり実行し、ステージ 8 のアーカイブで終了することです。失敗による終了、ユーザーが開始した停止、レビュー上限による一時停止は、いずれもフローの中断として扱い、手動モードに戻します。

OpenSpec 固有の注意事項

• ステージ 8 のアーカイブが完了すると、モードは自動的に手動モードに戻ります。
• --retry（修正を続行）：手動モードにリセットします。
• --resume（チェックポイントからの復旧）：チェックポイントのモードを維持します。
• OpenSpec のアーカイブ失敗は、フローの中断として扱い、手動モードに戻します。

無人運用時の代理終了

今回の実行のコントラクトまたはタスクカードに Stage-exit policy: ai-proxy（自動処理の担い手。キューの子タスクがあれば十分ですが、必須ではありません）が記録されている場合、各手動停止ポイントは ai-proxy-discipline に従った代理チェックポイントになります。簡易フリーズ（口頭でのトリガーは、占有を意味しません）については、そちらに記載されています。マージ、不可逆な操作、保護ブランチ、Jira への書き戻しは引き続き人間のみが行います（保留してチケットを作成）。それ以外のポリシー値が指定されている場合、または値がない場合は、今日の非代理動作になります。

停止ポイントの事前予測：この実行がフリーズ済みのコントラクト（課題とフリーズ済みの決定事項を含むキューの子タスク、またはすでに記述された独立した簡易フリーズ）から開始する場合、分析の前に予測テーブルを提示します。すべての手動終了ポイントについて、「フリーズ済みの決定事項でカバーされる」か「新しいチケットを作成する」かを示します。オーバーレイが実行途中に要求された場合は、簡易フリーズの出力後に、残りの終了ポイントの予測を提示し、その後、現在のステージを続行します（分析からやり直しません）。

キューの子タスクモード（goal-driven-queue によるディスパッチ）

goal-driven-queue によってディスパッチされた場合（呼び出しに明示的な queue-child コンテキストフラグがある場合。周囲のシグナルから推測することはありません）、このフローは次のように適応します。カードの目標条件に Jira 課題へのリンクを含めます。フリーズ済み決定事項ブロックでステージ 0～1 をまかないます。Stage-exit policy も引き継ぎます（ポリシーが ai-proxy の場合の占有は ai-proxy-discipline に従います。キューの子タスクがあれば十分ですが、必須ではありません）。開始時に停止ポイントの予測を提示します（すべての手動終了ポイントについて、「フリーズ済みの決定事項でカバーされる」か「新しいチケットを作成する」かを示します）。最終地点は アーカイブ + PR オープンです。OpenSpec の変更をアーカイブし（このモデルに標準で含まれるため、決して先送りしません）、PR をオープンした時点で停止します。マージと Jira への書き戻しは人間に委ねます（マージ権限の行使と外部トラッカーへの書き戻しを代理で行うことはありません）。これらは保留中のフォローアップとして、キューの受け入れパッケージに含めます。独立して使用する場合（フラグなし）、オーバーレイ／占有は引き続き Stage-exit policy に従いますが、キューの最終地点である アーカイブ + PR オープンは適用されません。終了処理は、このスキル本来のアーカイブ後にステージへ進む流れとなります（オーバーレイは、マージ／書き戻しまでを含む無条件の自動処理ではありません）。カードにキューの関連付けチェックのメモが含まれる場合は、この変更の design.md に ## Related Issues として記載します。この実行がキューの子タスクである場合、完了報告には課題、原因、完了した修正、および証拠の一覧を含めます。各証拠項目には、png、jpg、jpeg、webp のパスを引用した UI を開いて行うチェック、またはコマンドと短い出力概要を記載した UI 以外のチェックを含めます。画像がない場合、または空の場合は保留中とし、撮影がまだ必要であることを明記します。画像を捏造しないでください。UI を開いて確認した画像をチェックの根拠とする前に、completion-evidence-discipline に従って画像を確認します。この実行では HTML ページも証拠用 HTML も作成しません。

ステージ 0：前提条件の確認

重要な確認項目のいずれかに失敗した場合、フローを一時停止してください。修正に進んではいけません。

1. Jira URL／Jira ID を解析し、モード（manual／auto／force／retry／overlay）を検出します。Overlay では、ai-proxy-discipline に従って request thin freeze をトリガーし、その後 occupancy を実行します。
2. Jira データを読み取れることを確認します。jira-read {JIRA-ID} --live または mcp-atlassian を優先し、失敗した場合はローカルキャッシュにフォールバックします。両方とも失敗した場合は中止します。
3. Git のステータスを確認します。auto モードでは stash してもかまいません。manual モードでは、ユーザーに対処方法を確認します。
4. OpenSpec ワークスペースとネイティブスキルのゲート：opsx-workspace-gate を読み込み、プロジェクトルートの場所、openspec/ の確認、厳密なネイティブ OPSX スキルのゲートを実行します。これに合格したら、このワークフローを続行します。
5. OpenSpec のコマンドを確認します（プロジェクトルートから実行）。openspec list、openspec status、openspec validate を優先します。
6. 修正を続行する場合は、まず OpenSpec の change を特定します。現在のブランチ名からの推定を優先し、次に openspec/changes/*/{proposal.md,design.md,tasks.md} で Jira ID を検索し、その次に PR／MR の説明で OpenSpec change のパスを確認します。それでも一意に特定できない場合は、change 名を確認する質問をユーザーに必ず 1 つだけします。特定後は、openspec status --change <name>、openspec show <change-name>、design.md、tasks.md のチェックボックス、現在の Git ブランチから進捗を復元します。

OpenSpec の記録モデル

このスキルは、追加のランタイムディレクトリを作成しません。Jira のバグ修正サイクルは簡潔で明確に保ち、すべてのエンジニアリング記録は OpenSpec のアーティファクトに保存します。

ディレクトリ	目的	長期的な信頼できる情報源
Jira issue	問題の発生源、コメント、ステータスの遷移	いいえ — 外部プロセスの情報源
openspec/changes/<change-name>/	proposal、差分仕様、design、tasks、アーカイブ前の change の事実	はい — アーカイブ後に openspec/specs/ に統合
PR／MR	提出時の説明、検証の証拠、リスクとロールバック	いいえ — 提出時のコミュニケーション手段

OPSX の Jira 修正用に、追加のローカルランタイムディレクトリを作成してはいけません。修正を続行する場合は、OpenSpec change、tasks.md のチェックボックス、Git ブランチ、PR／MR のステータスから状態を復元します。

ステージ別ツール制約表

ステージ	✅ 許可	❌ 禁止
0 前提条件の確認	Read、Grep、Glob、Bash（読み取り専用の確認）、Jira API（読み取り専用）	Edit、Write、Git の書き込み操作
1 Jira の読み取り	Jira API、jira-read、Read、OPSX スキル（change の作成）、Bash（worktree ゲート）	ビジネスコードの Edit／Write、実装を変更する Bash
2 問題の分析	Read、Grep、WebSearch、analysis-core §1 に従う analysis-assist の Edit／Write（ロールバック用に登録が必要）	修正を実装するためのビジネスコードの変更
3 change の作成	ネイティブ OPSX スキル、Write（アーティファクト）	ビジネスコードの Edit
4 解決策の検討	Read、Grep	ビジネスコードの Edit／Write
5 計画の作成	Read、Write（tasks.md のみ）	ビジネスコードの Edit
6 実行と検証	すべて（Edit、Write、Bash、Git、テスト）。build／lint／tsc／test を実行する前に、node-version-discipline に従ってプロジェクトで宣言された Node バージョンに合わせます（そのスキルの SOP に記載された確認手順を実施）	検証の省略、チェックボックスの更新の省略
7 検証の確認	Read、Bash（テストコマンドのみ）、OPSX スキル（openspec-verify-change）	ビジネスコードの Edit／Write
8 提出と完了処理	Git、Jira API、OPSX スキル、Bash（パート C でカバレッジの実行を決定した場合は test-coverage-analyzer スクリプトも含む）	アーカイブの省略、Jira への書き戻しの省略

モードの違いの早見表

ステージ	手動モード	自動モード
0 事前確認	Git がクリーンでない場合 → ユーザーに確認	Git がクリーンでない場合 → 自動で stash
1 Jira の読み取り	変更名の候補を提示し、確認を待つ	ドラフトの変更を自動作成
2 問題の分析	自動モードと同じ	手動モードと同じ
3 変更の作成	ユーザーが名前を確認してから作成	自動生成して作成
4 解決策の検討	解決策の表を提示し、ユーザーの選択を待つ	最適な解決策を自動選択
5 計画の作成	計画を提示し、確認を待つ	通常：ステージ 6 に自動で進む。難しい／非常に難しい場合：一時停止
6 実行と検証	自動モードと同じ	手動モードと同じ
7 検証の確認	結果を提示し、確認を待つ	合否を自動判定。不合格の場合は自動で再試行（最大 2 ラウンド後、一時停止）
8 提出と完了	自動モードと同じ	手動モードと同じ

ステージ 1：Jira の読み取り

最初の成果物を書き込む前に（design.md の Jira コンテキスト）、git-worktree-discipline（worktree ゲート＋任意の分離）を読み込みます。

最新の Jira データを読み取り、できるだけ早く OpenSpec 成果物に記録します。チャットのコンテキストにだけ残してはいけません。

• Jira ID、タイトル、優先度、ステータス
• 説明、再現手順、期待される結果、実際の結果
• 添付ファイル、コメント、過去のコンテキスト
• データソース（ライブ／キャッシュ／ユーザー提供）

ステージ 1 の完了時に、OpenSpec の変更が決定または作成されている必要があります。

• 自動モード：ステージ 3 の命名規則に従ってドラフトの変更を作成し、Jira コンテキストを design.md に記録します。
• 手動モード：変更名の候補を提示して確認を待ちます。確認前に詳細な分析へ進んではいけません。
• 修正の続行：ステージ 0 で特定した既存の変更を再利用し、最新の Jira コンテキストを design.md に統合します。

ツールの制限：Jira API／jira-read は使用可能です。業務コードの Edit/Write は禁止です。実装を変更する Bash コマンドは禁止です。

完了したらステージ 2 に自動で進みます。

⚠️ 積極的な質問：clarifying-question-discipline に従ってください（1 ラウンドにつき質問は 1 つ。不明点が解消するまで複数ラウンドで進めます。まず明確化し、急いで答えないでください）。ドメイン用語が関係する場合は、domain-language-discipline にも従ってください。

🚩 重大な注意点：曖昧な点をいくつも 1 つのメッセージでユーザーに提示すること（厳格な規律への違反。clarifying-question-discipline を参照）。毎回、最も重要な質問を 1 つだけ尋ね、回答を得てから次の質問をしてください。

スコープの分割（任意、複数のサブシステムが関係する場合）

Jira の課題が 2 つ以上のサブシステムまたはモジュール（例：フロントエンド＋バックエンド＋データベース）にまたがる場合、ステージ 2 に進む前に分割します。

1. 関係するサブシステム／モジュールを列挙します。
2. それぞれについて、独立した根本原因があるか、独立した変更が必要か、主な変更に依存するかを記します。
3. 依存関係が強いサブシステムは 1 つの変更にまとめます。独立したサブシステムは、複数の変更への分割を検討し、それぞれ独自の修正フローを実行します。

分割の結論を design.md の Scope セクションに記録します。

ステージ 2：問題の分析

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

analysis-core に委任する

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

• {next-stage} = ステージ 3「OpenSpec の変更を作成」
• {root-cause step} = ステップ 5、{impact-assessment step} = ステップ 7、{upstream-eval step} = ステップ 6

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

このワークフローのオーケストレーション（維持）

analysis-core の骨組みに加えて、この段階では以下も完了します。

• 難易度の評価（簡単／中程度／難しい／非常に難しい）とパスの選択（簡易／段階的／完全）。スコープが拡大した場合はパスをアップグレードします
• 成果物の配置先：design.md の「Problem Analysis / Root Cause / Impact」に書き込みます（変更がすでに存在している必要があります。存在しない場合はステージ 1 に戻ります）
• 存在しない ❌／説明との不一致：いったん停止し、Jira コメントを書く前にユーザーの確認を得ます（jira-wiki-markup を読み込みます）

評価とパスの表：

レベル	条件	動作
簡単	3 ファイル以下、根本原因が明確	簡易パスを使用できます
中程度	4～10 ファイル、根本原因がおおむね明確	段階的パスを使用します
難しい	リスクが高い、または影響範囲が広い	ステージ 5 の後にレビューのため一時停止します
非常に難しい	根本原因が不明、アーキテクチャ変更、データ移行、API 契約の変更、リポジトリ横断	自動モードでは中止します。手動モードでは再確認が必要です

難易度	パス	要件
簡単	簡易	提案／差分仕様は簡易にできますが、検証を省略することはできません
中程度	段階的	提案／仕様／設計／タスクをすべて作成します
難しい／非常に難しい	完全	ステージ 1～8 を完全に実行します

🚩 危険信号：存在確認の省略、根本原因の分析不足、結論が design.md に記載されていない、曖昧さがあるのに計測が開始されない（analysis-core §3）、パスがアップグレードされていない、analysis-core／known-issue-research のゲートに違反している

---

ステージ 3：OpenSpec の変更を作成する

🔌 OPSX スキル呼び出しのルール：このステージ以降でネイティブ OPSX スキルに処理を委任する前に、必ずそのスキルの SKILL.md を読んでください。記憶を頼りに呼び出してはいけません。

Jira 課題の OpenSpec 変更を確認するか、作成します。ステージ 1 ですでに変更を作成または再利用している場合、このステージでは成果物の検証と完成のみを行います。手動モードでは最初に変更名の確認が必要です。自動モードでは変更名を生成して続行できます。

• 命名規則：fix-<jira-id-lower>-<short-topic>（例：fix-proj-12167-ai-summary-button）
• 作成：openspec-new-change に処理を委任します（その SKILL.md を読んでください。/opsx:new はエントリーエイリアスです）
• Jira の完全性：design.md には、少なくとも Jira Context / Root Cause / Options / Risk / Verification Notes を含める必要があります。提案／差分仕様のフィールド詳細は、reference.md の「ステージ 3 成果物フィールドチェックリスト」を参照してください

ステージ 4：解決策の検討とレビュー

進むべき道がまだ不明瞭な場合は、解決策の表や提案を作成する前に decision-fog-discipline に従います。ステージ 2 の根本原因とステージ 3 の成果物に基づき、解決策を 2～3 件提示します。

• 中核となる考え方
• 関連するファイル／モジュール
• OpenSpec の要件に対する網羅性
• メリット、デメリット、複雑さ、リスク
• 推奨する解決策

YAGNI：解決策は Jira の根本原因を修正し、差分仕様を満たすことに厳密に集中させ、必須ではない機能や過剰な設計を取り除きます。根本原因の範囲を超える追加は、「extra optimization」と明記し、リスクを引き受ける理由を示す必要があります。

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

手動モードでは解決策の表を出力し、ユーザーの選択を待ちます。自動モードでは最適な解決策を自動的に選択します。

staged-review-flow を読み込み、そのレビュー契約全体を実行します。このワークフローでの対応関係：{next-stage} = ステージ 5「計画の作成」；{artifact-sink} = openspec/changes/<change-name>/design.md；{extra-dimensions} = 仕様の網羅性（要件／シナリオ）と Jira のステータス境界（「fixed」への遷移のみ）；{batch-overcap-behavior} = N/A。

🚩 危険信号（ステージ 4）：

• 根本原因のみをレビューし、仕様の網羅性や副作用を確認していない
• 解決策が 1 件しかないという理由だけで、比較やレビューを省略している

ステージ 5：計画の作成

唯一のタスクリストとして openspec/changes/<change-name>/tasks.md を使用します。

タスクの要件：

• チェックボックスを使用します：- [ ] 1.1 ...
• 各項目は個別に検証できる十分な小ささにします。
• すべての差分仕様の要件とシナリオを網羅します。
• 必要なテスト、検証、ロールバック、OpenSpec アーカイブ、マージ後の Jira 書き戻しの手順を含めます。
• TBD、TODO、「適切に処理する」、「上記と同様」、またはその他の実行可能でない説明は使用しません。

手動モードでは計画を出力して待機します。自動モードでは通常、ステージ 6 に自動で進みます。難しいケースまたは非常に難しいケースでは確認を待つ必要があります。

🚩 危険信号（ステージ 5）：

• タスク項目に TBD、TODO、「適切に処理する」、「上記と同様」、またはその他の実行可能でない記述が含まれている
• タスクがすべての差分仕様の要件とシナリオを網羅していない
• テスト、検証、ロールバック、アーカイブ、またはマージ後の Jira 書き戻しの手順が欠けている
• タスクの粒度が大きすぎて個別に検証できない

ステージ 6：修正の実施と検証

本番コードを変更する前に、design-approval-gate に従います（手動：ユーザーの承認；自動／強制／リーン：明示的な例外と記録）。

コンテキスト予算：context-budget-discipline に従い、フェーズ境界でのリセットと圧縮のしきい値を評価します（台帳のパスはステージ 5 の計画／カードの供給元から取得）。リセットする場合は、事前に台帳へ完全な記録を残します。

6.1 修正ブランチの作成

ブランチの命名規則：

fix/jira-fix-<JIRA-ID>

複数のリポジトリにまたがる場合は、リポジトリごとにブランチを作成し、各リポジトリ、ブランチ、対応する OpenSpec 変更を PR／MR の説明に記載します。

6.2 タスクを実行する

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

tasks.md を順番に進めてください。

1. 一度に対応するのは現在のタスクだけです。
2. ビジネスコードに手を加える前に、提案、仕様、設計、タスクがすでに存在することを確認してください。
3. タスクを完了したら、すぐにチェックボックスを更新してください。 StrReplace を使って tasks.md の該当する [ ] を [x] に変更してください。タスクのグループが終わるまで更新をまとめてはいけません。これを省略すると、ステージ 7 の検証で CRITICAL の誤った未完了判定が報告されます。
4. 仕様または設計に誤りが見つかった場合は、まずその成果物を更新してから実装を続けてください。
5. 計画から逸脱する場合は、その理由を明示してください。動作上の契約に影響する場合は、ステージ 3 または 4 に戻ってください。

任意のトラッキングコメント：

// fix <JIRA-ID>

プロジェクトの規約で修正コメントが認められていない場合は、無理に追加せず、実行レポートに修正箇所を列挙してください。

6.2.5 テストファースト、その後にテストスイートを確実に整備（必須、ステージ 7 に進む前）

動作を変更する作業では、実装中に test-first-discipline に従ってください。tasks.md のすべてのチェックボックスにチェックを入れたら、ステージ 7 の検証に進む前に、次の手順を必ず実行してください。

test-suite-ensure を読み込んで呼び出し、この修正のロジックファイルを対象に mode=mandatory を指定してください。失敗した場合、または必要な足場の追加依頼が却下された場合は、ステージ 7 への移行を中断します。test-suite-ensure はテストファーストの要件を満たしません。

ステージ 7：検証

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

次の項目を網羅する必要があります。

1. OpenSpec の検証：
   • openspec-verify-change スキルが検出された場合 → その SKILL.md を読み、検証をそのスキルに委任します。
   • 見つからない場合 → openspec validate <change-name> または openspec validate --changes を直接実行します（CLI ツールの呼び出しであり、簡易化ではありません）。

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

2. エンジニアリング検証：テスト、lint、型チェック、ビルド（バージョンを合わせた環境で実行）
3. 動作の照合：delta-spec のすべての要件とシナリオを一つずつ確認します
4. Jira の照合：再現手順と期待結果／実際の結果が解消済みか確認します
5. 副作用の確認：関連モジュールとプラットフォームに影響があるか確認します。検証レポートには Node (declared vX) ✅/⚠️ not aligned を明記する必要があります
6. デバッグ・検証ループ：ステージ 2 でデバッグスキルを使って根本原因を特定した場合は、analysis-core §4 に従い、テストだけでなく、同じスキルを使って修正を検証します
7. Figma のピクセル検証：目標、カード、課題、計画に figma.com または node-id= が含まれる場合、あるいは今回の実行で Figma を基に実装した場合は、figma-pixel-verify を読み込み、その手順に従います。計測済みレポート（成果物の Verify セクション、または Spec ソースの同階層ファイル）がない場合、この検証ステージは合格になりません。spec-gap が FAIL の場合、検証に合格したことにはなりません。表を完成させるために figma-pixel-implement に戻ってください。同じ実行内で実装していない場合でも、整合性の確認が必要であれば読み込みます。このステージが合格するのは、レポートの全体ステータスが PASS（受け入れ済みの残差を含む）で、かつその計測方法がレイアウトを伴うもの（storybook、isolated-harness、preview、full-app、layout-probe）である場合に限ります。それ以外の結果はこのステージの不合格となり、修正と再計測のループのために実装ステージへ戻ります。このステージでは、figma-pixel-verify スキルに含まれる scripts/check-figma-verify-report.mjs もそのレポートに対して実行します。終了コードが 0 以外の場合、このステージは不合格です。

検証の実行は runtime-verification-discipline に従います（強い依存関係）：AI は環境内で自ら検証を実行します。手動検証項目として記載できるのは、真のハード境界と分類された場合のみで、その理由を明記する必要があります。

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

出力形式：reference.md の「Stage 7 Verification Results」を参照してください。

検証に失敗した場合、PR を提出してはいけません。実行記録は tasks.md のチェックボックス、PR/MR の説明、design.md の Verification Notes に記載します。

ステージ 8：アーカイブ、PR の提出、マージ、クローズアウト

8.1 OpenSpec のアーカイブ

アーカイブ前の同期手順：

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

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

マージまたはマージ準備の前に、アーカイブが完了していることを確認します（merge-discipline のパート A に準拠）：

• アクティブな OpenSpec 変更が関連付けられている場合：まず必ずアーカイブします（メイン仕様を同期し、openspec/changes/archive/ に移動します）。差分を確認してからマージします。「マージ後にアーカイブ」は通常の手順として決して行いません。
• 関連する変更がない PR：パート A をそのまま通過し、アーカイブは不要です。

デフォルトでは、検証に合格した後、まずアーカイブし、openspec/specs/ の更新と openspec/changes/archive/ への移動が差分に含まれていることを確認してから、成果物を引き渡して作業を終了します。

8.2 コミットと PR（delivery-discipline）

引き渡し前に、以下を確認します：

• 関連するすべての tasks.md のチェックボックスが完了していること。
• OpenSpec の成果物、コード変更、必要な検証メモがすべて差分または PR/MR の説明に含まれていること。
• 検証に合格しているか、手動検証項目が明示されていること。

delivery-discipline を読み込み、その指示に従います。以下を指定します：

• {commit-context}：fix(<scope>): <JIRA-ID> <subject> を優先します
• {pr-body-extra}：Jira リンク、根本原因、修正方法、OpenSpec の変更パス、変更ファイル一覧、検証結果、リスクとロールバック

8.3 ブランチの終了処理

アーカイブ、引き渡し、差分確認が完了したら、メニュー（PR／マージ／保持／続行）のために feature-branch-closeout を読み込みます。検証に合格していない場合や、アーカイブが完了していない場合は、決して完了を宣言してはいけません。

順序の制約：アーカイブ（8.1）→ delivery-discipline（8.2）→ feature-branch-closeout（8.3）→ マージ時は merge-discipline（8.3.1）→ マージを実行 → Jira への書き戻し（8.4）。保持／続行を選択した場合は、マージ規律と Jira への書き戻しの両方を省略します。

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

マージ時（終了処理から、またはユーザーが直接マージを指示した場合）は、merge-discipline を読み込み、パート A → B → C → R → D を実行します。マージ前チェックリストは merge-discipline/reference.md にあります。暗黙に省略してはいけません。

8.4 Jira への書き戻し（マージ完了後）

PR/MR がマージされ、コードがメインブランチに反映されたら、修正が反映されたことを示すよう Jira のステータスを書き戻します。強い依存関係である jira-status-writeback を読み込み、ステータス遷移と修正コメントについてその SOP に従います（jira-wiki-markup が Wiki の body を作成します）。このワークフローでは、次のフィールド対応表を使用します：

jira-status-writeback のフィールド	値
修正ブランチ／コミット／PR/MR URL	修正ブランチ名／マージ済みの先端 SHA／PR/MR リンク
根本原因	ステージ 2 の根本原因の要約
修正の概要	修正方法
変更ファイル	変更ファイル一覧
検証	ステージ 7 の検証シナリオ
その他	OpenSpec の変更パス、リスク、または QA のフォローアップ項目

終了処理の記録は、PR/MR、Jira コメント、OpenSpec のアーカイブ結果を正とします。

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

アーカイブとブランチのクローズ処理が完了したら（マージを実行した場合は Jira への書き戻しも完了したら）、learn-and-improve を読み込み、そのフレームワークに従います。通常のフローでアーカイブされた OpenSpec アーティファクトは、そのスキルの蓄積価値ゲートの対象外です。AI エンジニアリングの知識（AGENTS.md、ルール、スキルなど）については、そのスキルの格納先決定ツリーを使用します。書き込みには、まずユーザーからの明示的な依頼が必要です。

🚩 危険信号（ステージ 8）：

• 検証に合格する前に PR を提出する
• Jira コメントを jira_transition_issue の comment パラメーターに渡す、または権限を超えてステータスを「closed」／「verified」に遷移させる（SOP：jira-status-writeback）
• アーカイブに失敗した後、openspec/ ディレクトリを手動で操作する
• PR の説明に OpenSpec の変更パスまたは検証の証拠が記載されていない
• ask の設定で、ユーザーに尋ねずにアナライザーをデフォルトで実行する（merge-discipline のパート C を参照）
• アーカイブ（8.1）が完了する前にマージ規律を開始する（順序：8.1 アーカイブ → 8.2 delivery-discipline → 8.3 ブランチのクローズ処理 → 8.3.1 マージ規律 → マージ → 8.4 Jira への書き戻し）

OPSX Jira 修正の一括処理

opsx-jira-fix-queue スキルを使用します（薄いシェル：Jira のリストを解析して、Engine: opsx-jira-fix-workflow を指定し goal-driven-queue にキュー登録します。このワークフローをループしたりマージしたりはしません）。キューがすでに記録した関連性の判断は、各変更の design.md に ## Related Issues として記載します。

よくある間違い

ここでは、このスキルに固有の、気づきにくい落とし穴のみを挙げています。マージ／カバレッジ／アーカイブについては merge-discipline、プロジェクトルート／openspec/／ネイティブスキルのゲートについては opsx-workspace-gate、Jira への書き戻しの SOP については jira-status-writeback、コメントの Wiki マークアップについては jira-wiki-markup を参照してください。ステージ本文にすでに記載されているルールは繰り返しません。

間違い	結果	修正
余分なローカルランタイムディレクトリを作成する	OpenSpec の外部に 2 つ目の記録システムができる	すべて OpenSpec アーティファクト、PR／MR、Jira コメントに記録する
OpenSpec にだけ書き込み、Jira に書き戻さない	Jira のプロセスが破綻し、QA がフォローアップできなくなる	ステージ 8.4 のマージ後に jira-status-writeback を読み込み、書き戻しを完了する
ステージ 8.4 で jira-status-writeback の 2 段階 API の詳細やステータス権限のロジックを繰り返す	jira-status-writeback と内容がずれ、コメントが失われたり、課題が誤ってクローズされたりする	ステージ 8.4 ではフィールドマップのみを渡す。SOP の詳細は jira-status-writeback が担う
簡単な修正に OPSX の経路を使う	フローが重くなりすぎる	トレーサビリティの蓄積が不要な場合は jira-fix-workflow を使用する
リストに基づいて機械的に一括処理する	修正の重複、依存関係の見落とし、動作の競合が発生する	実行前後に課題間の関係を特定し、Related Issues / Risk / Dependencies に記録する
ステージ 2 の分析直後に提案を作成する	Why と What がつながらず、アーティファクトを書き直す必要が生じる	ステージ 4 で解決策を選んだ後、1 回で提案を作成する
design.md に Jira Context / Root Cause / Options / Risk / Verification Notes がない	課題ごとの振り返りができない	この 5 つのセクションが Jira×OPSX の最低限の完全性基準となる
MODIFIED に断片だけを書き込む、またはスキルの短縮名を間違える	アーカイブで要件が失われる／SKILL.md が見つからない	ブロック全体をコピーしてから編集する。openspec-*-change の名前を正確に使用する

最低限の成功基準

1 回の実行が完了していること：ネイティブスキルを使って OpenSpec 変更に proposal / delta specs / design / tasks が揃っていること、PR／MR が作成または更新されていること、Jira にコメントがあり（許可されている場合は）「fixed」に遷移していること、OpenSpec がアーカイブされていること（または PR にアーカイブ方針と担当者が記載されていること）、検証の証拠が記録されていること。