<!-- syncToGlobal: true --> <!-- author: aktsmm --> <!-- repository: https://github.com/aktsmm/Agent-Customization --> <!-- license: CC BY-NC-SA 4.0 --> <!-- copyright: Copyright (c) 2025 aktsmm -->

review workflow runtime

ワークフロー定義と、それが参照する scripts / hooks / validators / CLIs を横断して、実行時に本当に安全に動くかをレビューする。

When to Use

• 使う: agent / skill / instruction / AGENTS が scripts / hooks / validators / CLI を参照している workflow を確認したいとき
• 使う: dry-run -> apply -> verify、I/O schema、冪等性、重複防止、cleanup、error handling が実装と一致しているか見たいとき
• 使う: scripts の冗長な処理、重複関数、長すぎる分岐、不要な手順を見つけて安全に整理したいとき
• 使う: workflow が「設計上は良い」が、実スクリプトや実行手順まで噛み合っているか不安なとき
• 使わない: agent / instruction / skill の構造・SSOT だけを見たいとき。その場合は /review-workflow-structure を使う
• 使わない: 通常のコード品質レビューだけをしたいとき。その場合は通常の review として扱う

Default Behavior

• 既定スコープは referenced-only: 対象 workflow 資産から明示参照された scripts / hooks / validators / CLIs だけを追う
• all / 徹底的 / deep（大文字小文字を区別しない）が指定された場合は、参照された script と同じ workflow folder / scripts folder の近接ファイルも確認する
• 既定の修正モードは safe-auto-fix: 低リスク修正は実施してよい
• review-only / read-only が指定された場合は変更せず、fix と競合した場合も read-only を優先する
• rubberduck / rubber duck は名前付き agent ではなく、各前提を言語化して根拠で反証するレビュー手法として扱う。利用可能な評価サブエージェントにこの手法を明示して委譲し、登録済み RubberDuck agent の存在は要求しない
• destructive operation、外部反映、認証・secret、履歴改変、広範囲 refactor は実行前に確認する

Reference Sources

ワークスペース内に存在する場合は、次を補助 SSOT として読む。

• .github/skills/agentic-workflow-guide/SKILL.md（なければ ~/.copilot/skills/ 側）
• .github/skills/agentic-workflow-guide/references/review-checklist.md（同上）
• .github/instructions/**.instructions.md のうち対象 script / workflow に apply されるもの
• AGENTS.md / .github/copilot-instructions.md / 関連 .agent.md / 関連 skill

存在しない場合は、この skill 単体のチェック項目でレビューを続行する。

Context Gate

1. 対象 workflow 資産と、read / search / validation / subagent / edit に必要な capability を特定する。
2. 必須 capability が無い場合は変更せず、未確認対象と再開条件を伴う INCOMPLETE とする。
3. Markdown links、backtick path、code block、CLI examples、script 名から参照 script / hook / validator を抽出する。
4. 抽出した path が実在するか確認する。
5. script が存在しない場合は missing script contract として報告する。
6. script が見つからない workflow は、workflow logic review のみ実施し、script coverage が無いことを明記する。
7. Rubber Duck 指定時はサブレビューの path、行、件数、重複、欠落の主張を実ファイルで照合してから採用する。サブエージェントが利用できない場合は fallback review を行い、総合判定を INCOMPLETE とする。

Review Checks

1. Workflow Logic

• trigger / mode / phase / stop condition が明確か
• preflight、apply、verify、cleanup の順序が実行可能か
• user confirmation が必要な判断と、自動実行してよい判断が分かれているか
• retry / resume / partial failure の扱いがあるか

2. Script Contract

• script path が実在し、呼び出し例と一致しているか
• CLI args、default 値、required args、exit code、stdout/stderr の前提が workflow 側と一致しているか
• --help、schema、README、docstring のいずれかで使用法を確認できるか
• dry-run / apply / verify の境界が実装または runbook にあるか
• script output が後続 agent / prompt の期待する JSON / Markdown / file に合っているか

3. Idempotency and Safety

• 再実行で重複作成、二重投入、二重送信、二重削除が起きないか
• 既存 state / artifact / ID を確認してから mutation するか
• destructive operation は明示 flag や confirmation を要求するか
• secret、token、local absolute path、個人環境値を出力や成果物へ混ぜないか

4. Deterministic Offload

• extract / count / validate / diff / format / parse / lint が LLM ループに残っていないか
• LLM 判断の前後に、script / schema / hook による fail-fast gate があるか
• file-based IR を使う場合、materialize する理由と cleanup 方針があるか

5. Script Simplicity

• 同じ処理、同じ validation、同じ CLI 呼び出し、同じ変換ロジックが重複していないか
• 長い if / switch / try-catch / copy-paste block を小さな helper へ切り出せるか
• 設定値、path、magic number、出力 schema を複数箇所に持っていないか
• 1 コマンドや既存 helper で済む連続処理を script / prompt / agent が重ねていないか
• リファクタ後も CLI contract、exit code、output schema、side effect が変わらないか

6. Verification

可能な範囲で read-only / deterministic な確認を実行する。

• Markdown link / referenced path の存在確認
• Python: 構文確認、該当テスト、--help、安全な dry-run
• PowerShell: [scriptblock]::Create((Get-Content -Raw -Encoding UTF8 <file>))
• Node: package scripts、typecheck、lint、dry-run 相当
• 各検査を PASS / FAIL / NOT_RUN で記録し、実行できない場合は理由と代替確認を明記する
• deterministic な検査を限定 read や目視で代替した場合、その項目を PASS に昇格させない
• 必須検査が NOT_RUN、必須ファイルが read 不可、または coverage が不足する場合は修正を止め、総合判定を INCOMPLETE とする
• 一時 validator、IR、log を作った場合は検証後に削除する

Safe-Auto-Fix Policy

fix / all fix は優先度で選別しない。下の「確認してから行うもの」に当たらない指摘は Medium 以下も全件修正し、残す指摘には確認が必要な条件か維持の根拠を明記する。Low 以外を修正したときは rubberduck 指定がなくても、修正後 diff を別モデルの評価サブエージェントで Rubber Duck レビューし、指摘を反映してから完了とする（review-only では不要）。

既定の safe-auto-fix で自動修正してよいもの。

• 壊れた相対リンクや stale script path の修正（正しい実在 path が一意に分かる場合）
• workflow 資産側の CLI example / option 名 / output field 名の修正（script 実装が正本として確認できる場合）
• frontmatter、typo、deprecated wording、明らかな重複説明の圧縮
• 冗長な helper / validation / option handling の統合（CLI contract、output schema、side effect が変わらない場合）
• 長い処理を読みやすい小関数へ切り出すリファクタ（テストまたは構文確認で検証できる場合）
• read-only validation のための一時 script 作成と作業後 cleanup
• 小さな guard / validation 追加で、外部副作用や既存 CLI contract を変えないもの

低リスク修正と同じ検査の再実行は最大 3 回で止める。解消しない場合は NEEDS_IMPROVEMENT として残件と再開条件を報告する。

確認してから行うもの。

• script の mutation behavior、外部 API 呼び出し、認証、削除、submit、publish、apply を変える修正
• CLI contract の破壊的変更
• 大きな refactor、ファイル移動、履歴改変
• 性能改善や抽象化を目的にした、挙動差を検証しにくい rewrite
• 一意に正しい path / schema / expected behavior が判断できない修正

Output Format

✅ Good Points

• {良い点}

⚠️ Improvements Needed

• {優先度} [{削除|統合|分離|移動|追加|維持|修正}] {カテゴリ}: {file}:{line} -> {解決策} | Impact={runtime-affected|review-only} | Evidence={script/doc/test}

Script Contract Matrix

Workflow Asset	Referenced Script / Tool	Contract Status	Verification
{path}	{script}	PASS / MISMATCH / MISSING / NOT_RUN	{確認内容}

Fixes Applied

• {変更したファイルと理由。review-only の場合は None}

Verification

• {実行した検査、exit code、未実行理由}

Recommendation

• {総合評価 PASS / NEEDS_IMPROVEMENT / INCOMPLETE と次アクション}

Completion Criteria

• 対象 workflow 資産を読んだ
• 参照 scripts / hooks / validators / CLIs を抽出した
• 実在確認と contract 照合をした
• script output と workflow input の整合性を確認した
• 冗長処理、重複ロジック、不要な連続手順を確認した
• dry-run / apply / verify / cleanup の境界を確認した
• Rubber Duck 指定時は評価サブエージェントを実行し、その主張を実ファイルで照合した。利用不可時は INCOMPLETE として報告した
• safe-auto-fix の範囲内で必要な修正を行った、または review-only として停止した
• 検証結果と未確認リスクを報告した