プラン実行

実装計画をステップバイステップで実行します。各ステップは実装、検証、コミットされてから次のステップに進みます。進捗は永続的に追跡されるため、セッションの喪失後も保持されます。

実行モード

このスキルは呼び出し方法に基づいて動作を適応させます:

• ソロモード(do-issue-solo から呼び出された場合): 自律的に作業します。本当に詰まったときまたは問題が曖昧な場合のみ一時停止します。回復可能な問題は対処して進めます。
• ガイド付きモード(do-issue-guided から呼び出された場合): ユーザーにチェックポイントを提供します。不確実な場合は一時停止し、自然な区切り目で進捗を報告します。

digraph mode {
    "Called from do-issue-solo?" [shape=diamond];
    "Solo mode" [shape=box];
    "Guided mode" [shape=box];

    "Called from do-issue-solo?" -> "Solo mode" [label="yes"];
    "Called from do-issue-solo?" -> "Guided mode" [label="no"];
}

実行ループ

digraph execute {
    "Load plan" [shape=box];
    "Check for prior progress" [shape=box];
    "Pick next uncompleted step" [shape=box];
    "Mark step in-progress" [shape=box];
    "Implement the change" [shape=box];
    "Run verification" [shape=box];
    "Verification passes?" [shape=diamond];
    "Diagnose and fix" [shape=box];
    "Fix attempt count" [shape=diamond];
    "Commit" [shape=box];
    "Mark step complete" [shape=box];
    "Update progress on issue" [shape=box];
    "More steps?" [shape=diamond];
    "Run full verification suite" [shape=box];
    "Acceptance criteria check" [shape=box];

    "Load plan" -> "Check for prior progress";
    "Check for prior progress" -> "Pick next uncompleted step";
    "Pick next uncompleted step" -> "Mark step in-progress";
    "Mark step in-progress" -> "Implement the change";
    "Implement the change" -> "Run verification";
    "Run verification" -> "Verification passes?";
    "Verification passes?" -> "Commit" [label="yes"];
    "Verification passes?" -> "Diagnose and fix" [label="no"];
    "Diagnose and fix" -> "Fix attempt count";
    "Fix attempt count" -> "Run verification" [label="<= 2 attempts"];
    "Fix attempt count" -> "Escalate (see Failure Handling)" [label="> 2 attempts"];
    "Commit" -> "Mark step complete";
    "Mark step complete" -> "Update progress on issue";
    "Update progress on issue" -> "More steps?";
    "More steps?" -> "Pick next uncompleted step" [label="yes"];
    "More steps?" -> "Run full verification suite" [label="no"];
    "Run full verification suite" -> "Acceptance criteria check";
}

1. タスクを読み込む

以下のいずれかからタスクリストを読み込みます:

• GitHub イシューのタスクコメント(do-issue から作業している場合)
• タスクリスト直接(スタンドアロンで呼び出した場合)

2. 以前の進捗を確認する

クラッシュまたは新規セッション後に再開する場合は、どこから再開するかを判定します:

• タスクコメントを読み込みチェックボックスを解析します(- [x] = 完了、- [ ] = 保留中)
• git log と相互参照します — チェックが外れているのにコミットが存在するタスクがある場合、コメント更新が失われています。今すぐチェックしてください。
• 最初に本当にチェックが外れているタスクから再開します。

# タスクコメントを読み込む(イシューモード)
REPO=$(jq -r '.repo' .claude/issue-state.json)
COMMENT_ID=$(jq -r '.comments.tasks' .claude/issue-state.json)
gh api "repos/$REPO/issues/comments/$COMMENT_ID" --jq '.body'

3. 各タスクを実行する

リスト内の各タスクについて:

1. 進行中にマークする — 作業中のタスクをメモします
2. 実装する — タスクで説明されている変更を行います
3. 検証する — mav-local-verification スキルに従って検証(リント、型チェック、テスト)を実行します
4. 必要に応じて修正する — 検証が失敗した場合は診断と修正を行います(失敗処理を参照)
5. コミットする — イシュー番号を参照する説明的なメッセージを使用し、conventional commits を従います
6. 完了にマークする — タスクコメントを更新してタスクをチェックオフします

複数のタスクを 1 つのコミットにバッチ処理しないでください(例えば 1 行の変更とそのインポート以外)。

4. 進捗を更新する

各タスク完了後、タスクコメントを更新してタスクをチェックオフします:

REPO=$(jq -r '.repo' .claude/issue-state.json)
COMMENT_ID=$(jq -r '.comments.tasks' .claude/issue-state.json)

CURRENT_BODY=$(gh api "repos/$REPO/issues/comments/$COMMENT_ID" --jq '.body')
# 完了したタスクのチェックボックスを更新 — 書き込みはアプリの
# ID を通じて行われるため、コメントの編集履歴は元の作成者と一致します
# (完全な ID ルールについては mav-github-issue-workflow を参照してください)。
uv run maverick gh-app gh -- api "repos/$REPO/issues/comments/$COMMENT_ID" \
  -X PATCH \
  -f body="$UPDATED_BODY"

これにより進捗がセッション失敗、VM の喪失、またはサブエージェントクラッシュ後も保持されます。

5. 完全な検証スイートを実行する

すべてのステップが完了した後、プロジェクトの完全な検証スイートを実行します:

• リント
• 型チェック
• すべてのテスト

見つかった問題を修正します。失敗しているチェックがある状態では受け入れ基準に進まないでください。

失敗処理

digraph failure {
    "Verification fails" [shape=box];
    "Diagnose the failure" [shape=box];
    "Fix and re-verify" [shape=box];
    "Passes now?" [shape=diamond];
    "Attempt count" [shape=diamond];
    "Apply mav-systematic-debugging skill" [shape=box];
    "Still stuck?" [shape=diamond];
    "Continue" [shape=box];

    "Verification fails" -> "Diagnose the failure";
    "Diagnose the failure" -> "Fix and re-verify";
    "Fix and re-verify" -> "Passes now?";
    "Passes now?" -> "Continue" [label="yes"];
    "Passes now?" -> "Attempt count" [label="no"];
    "Attempt count" -> "Fix and re-verify" [label="<= 2"];
    "Attempt count" -> "Apply mav-systematic-debugging skill" [label="> 2"];
    "Apply mav-systematic-debugging skill" -> "Still stuck?";
    "Still stuck?" -> "Fix and re-verify" [label="no — found the issue"];
    "Still stuck?" -> "Escalate per mode" [label="yes"];
}

モードによるエスカレーション

状況	ソロ	ガイド付き
2 回の修正試行後にステップが失敗する	mav-systematic-debugging スキルを適用します。それでも詰まっている場合、ユーザーに助けを求めます。	すぐにユーザーに助けを求めます。
設計の仮定が間違っていることが判明する	設計に照らし合わせて再評価します。確信があれば手法を調整します。変更が根本的な場合のみユーザーに質問します。	調整前にユーザーと一時停止して相談します。
外部ブロッカー(API ダウン、依存関係の欠落)	ブロッカーを文書化してユーザーに質問します。	ブロッカーを文書化してユーザーに質問します。
実装手法について不確実である	最も可能性の高い手法を試します。うまくいかない場合は別の手法を試します。最後の手段としてのみユーザーに質問します。	どの手法を採用するかをユーザーに質問します。

してはいけないこと

• 失敗している検証をスキップしないでください。 まず修正してください。
• 壊れたコードベースのまま次のステップに進まないでください。 各コミットはコードベースを正常な状態のままにする必要があります。
• 設計を黙って変更しないでください。 プランを変更する必要がある場合、プランコメントを更新し(ガイド付きモードでは)ユーザーに通知します。
• 同じ修正を繰り返し再試行しないでください。 同じ修正が 2 回失敗した場合、診断が間違っています。一歩引き返して異なる視点で考えてください。

ガイド付きモードのチェックポイント

ガイド付きモードでは、自然な区切り目で簡潔な進捗チェックポイントを提供します:

• 3～4 ステップごと: 「ステップ 1～4 が完了しました。ステップ 5～8 に移行します。進行状況は順調です。」
• 予期しないことが発生した場合: 「ステップ 3 で API レスポンス形式が設計で想定されていた形式と異なることが判明しました。解析ロジックを調整しました。続行します。」
• すべてのステップが完了した後: 「7 ステップすべてが完了しました。完全な検証スイートは合格しています。受け入れ基準の確認に進む準備ができています。」

チェックポイントは簡潔に保ちます — 1～2 文です。何かが間違っていない限り、続行の承認を求めないでください。

受け入れ基準の確認

すべてのステップが完了し、完全な検証スイートが合格した後:

1. 元のイシュー要件を再読します
2. 各受け入れ基準を確認し、実装によって満たされていることを確認します
3. 満たされていない基準がある場合:
   • 何が不足しているかを特定します
   • それに対処するための追加ステップを追加します
   • 上記の同じループを使用してこれらのステップを実行します
4. 追加後に再度完全な検証スイートを実行します

すべての受け入れ基準が満たされ、すべてのチェックが合格するまでコードレビューに進まないでください。

<!-- maverick-plugin-version: 3.1.1-dev -->