fix-review-point

name	fix-review-point
description	Address unresolved review comments on specified PR
argument-hint	[pr-number]
hooks	{"Stop":[{"matcher":"","hooks":[{"type":"command","command":"node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop-servers.mjs\""}]}]}

Fix Review Point

GitHub PR $0 の未解決レビューコメントに対応し、修正のコミット・push・Resolve・description更新までを完遂するスキルです。Instructionsに従って順に実行し、各フェーズの「完了条件」を満たさないまま次のフェーズに進まないこと。

自律実行モード: ユーザーへの確認を求めずに最後まで自律的に完遂すること。判断が必要な場面では本ドキュメントの既定挙動に従って自動的に意思決定し、処理を継続する。確認のために停止することは禁止（フェーズ0の安全ガード条件に該当する場合のみ中断可）。

Instructions

実行モードの制約

本スキル固有のリスク: 本スキルは claude-task-worker の cc-fix-onetime ラベルをトリガーに自動起動され、ワーカーはスキルプロセスの同期完了を根拠に cc-fix-onetime の除去やコールバックコメント投稿を進める。処理が未完のままターンを終えると、修正コミット未 push のまま Resolve だけ済まされたり、レビュー未対応のまま fix ラベルが外れて放置される状態壊れが起きる。

スコープと出力の規律

• 指摘された範囲だけを直す: レビュアーの指摘を解消する変更に限定し、周辺のリファクタ・命名整理・気づいた別の改善を勝手に足さない（レビュアーの意図から外れた差分はレビューをやり直させる）。気づいた点は修正せず、最終報告に1行で挙げるだけにする
• 指摘が誤りだと考えた場合: 1-2行で根拠を添えてPRコメントに残し、そのうえで指摘の意図に沿って対応する（黙って無視・縮小・別物への置き換えをしない）
• 成果物の文章量は内容に見合わせる: PR description の更新・修正履歴・最終報告は必要な実質だけを書く。同じ内容の言い換え、定型の埋め草セクションを足さない
• 最終報告は結論から: 1文目で「何件の指摘に対応したか / どこで止まったか」を述べ、詳細をその後に置く

実装の委任（判断ロジック）

メインエージェント（本スキルを実行しているセッション本体）の役割は「指摘の分解・委譲・検証・統合」であり、規模の大きい指摘・並列化できる指摘の修正主体はサブエージェントである。ただし、レビュー指摘には1ファイル数行で済むものが相当数あり、数回のツール呼び出しで自分で終わる修正まで委譲すると、ブリーフィング作成とサブエージェント側の再探索でコストと時間が倍になる。指摘ごとに下記の判定を行って委譲/直接編集を決める（プラン全体で一括判定しない）。

判定は着手前に行い、判定結果（どちらを選んだか・根拠となった条件）を記録して最終報告の自己監査に載せる。

ステップ1: 無条件で委譲するもの（1つでも該当したら即委譲。以降の判定はしない）

• UI/コンポーネント実装・デザイン適用 → frontend-implementer
• .pen ファイルの編集・更新 → pencil-design-updater
• 2ファイル以上に触れる見込みがある
• 新規ファイルの作成を含む
• 着手前に探索が必要（編集対象のファイルパスと関数/シンボル名を、いま即答できない）
• 変更行数の見積もりが概ね20行を超える
• 依存追加・設定変更・スキーマ/マイグレーション変更を含む
• 指摘が設計・責務分割・安全性の再考を求めている（字面どおりの置換で済まないもの。要約して渡すと劣化するため、コメント全文を渡して委譲する）
• 独立して並列実行できる指摘が他に2件以上ある（メインが自分で直すと並列性を捨てることになる）

ステップ2: 直接編集してよい条件（すべて満たす場合のみ）

1. 対象が単一ファイルで、変更が概ね10行以内
2. 対象箇所がすでにメインの文脈にある（create-review-fix-plan の返却が file:line を直接指している、自分で Read 済み、CodeGraph の出力に含まれる、または失敗ログが該当行を指している）
3. 追加の調査・仕様確認が不要で、修正内容が一意に定まる（typo、命名の統一、不要コメントの削除、import の追加、型注釈の修正、リテラルの定数化など）
4. 指摘が「何をどう直すか」まで具体的に書かれており、解釈の余地がない
5. 他のサブエージェントの完了待ちを遅らせない

フェーズ4の収束ループ（テスト/Lint/ビルド失敗の修正）にも同じ条件を適用する。

委譲の量の制御

• 1指摘に1エージェント。1体で完結する指摘に複数体を重ねて起動しない
• 検証目的でサブエージェントを起動しない。成果物の確認は git diff / テスト・Lintの実行でメインが自分で行う
• 並列起動は「対象ファイルが重ならない独立した指摘」に限る（判断基準は「並列 vs 逐次の判断」節）

ステップ3: 判定が割れたら委譲する

上記のどちらとも言い切れない場合は委譲側に倒す。「たぶん小さい」「たぶん1ファイルで済む」は該当しない根拠にならない。軽量な指摘の受け皿として lightweight-assistant を使う。

滑り坂ガード

小修正の直接編集を積み上げてPR全体を自分で直してしまう事故を防ぐため、以下を守る。

• 直接編集は指摘1件ごとに独立して判定する。「さっき直したついでに」で連鎖させない
• 直接編集したらその指摘の範囲で完結させ、関連しそうな箇所へ手を広げない（範囲外の変更はレビュアーの意図から外れる）
• 1セッション内で直接編集が3件に達したら、以降の指摘はすべて委譲へ切り替える（それだけ小粒な指摘が続く場合でも、委譲すれば並列化できるため）

ツールの使い分け（直接編集する場合も適用）

• ファイル編集は必ず Edit / Write を使う。sed -i / ファイルへの > >> リダイレクト / patch / cp / mv / rm などシェル経由の書き換えは、差分が検証できずレビューにも残らないため使わない
• gh ... --body-file - へのヒアドキュメントのように、リポジトリのファイルを変更しない標準入力の利用は可
• git stash / gh pr checkout / git commit など、スキル本文が指示する git 操作は可
• 依存追加（npm install <pkg> など）はステップ1で委譲対象のため、メインからは実行しない

E2Eテストの取り扱い（共通ルール）

対象プロジェクトにE2Eテストが存在し、かつ修正がユーザー操作フローに影響する場合、ユニットテストと同様にE2Eテストの実装・更新も本スキルの完遂条件に含める。フェーズ1の完了後（サブエージェント起動前）に以下のいずれかに該当するかを一度だけ確認し、判定結果（存在有無・テストの所在・実行コマンド）を後続フェーズで使い回す：

• E2Eフレームワークの設定ファイルが存在する（playwright.config.* / cypress.config.* / wdio.conf.* / nightwatch.conf.* など）
• e2e/ / tests/e2e/ / cypress/ などのE2Eテスト用ディレクトリが存在する
• package.json の scripts に test:e2e / e2e 等のE2Eテスト実行コマンドがある

E2Eテストが存在すると判定した場合：

• ユーザー操作フロー（画面遷移・フォーム入力・API連携・CLIの入出力など、既存E2Eテストが検証している境界）に影響する修正タスクの完了条件に「該当フローのE2Eテストの追加・更新」を含める
• フェーズ3のブリーフィングに、E2Eテストの所在・実行コマンド・既存E2Eテストの記述パターンの参照先を含める
• フェーズ4の収束ループでE2Eテストも実行する

E2Eテストが存在しない場合は、レビュー指摘が明示的に要求しない限りE2Eテスト基盤を新規導入しない（スコープ外の変更となるため）。

フェーズ0: 事前チェックとPRチェックアウト

並列で以下を確認する。1つでも失敗したら、その場で原因を解消してから先に進むこと。

• gh pr view $0 --json number,state,headRefName,isDraft でPRが存在し OPEN であることを確認する。CLOSED/MERGEDなら処理を中断
• gh pr checkout $0 >/dev/null 2>&1 でPRブランチをチェックアウト
• pwd で .claude/worktrees/ 配下にいることを確認する。worktree外なら安全のため処理を中断する（デフォルトブランチで作業してはならない）
• gh repo view --json defaultBranchRef -q .defaultBranchRef.name でデフォルトブランチ名を取得し、git rev-parse --abbrev-ref HEAD の現在ブランチと一致する場合は安全のため中断する。デフォルトブランチ名の取得失敗も中断する（fail-safe）
• git status --short で未コミット変更があれば git stash push -u -m "fix-review-point auto-stash $0" で自動退避してから先に進む（ユーザーへの確認は行わない）

完了条件: worktree内、PRブランチ（デフォルトブランチ以外）にチェックアウト済み、PR OPEN が確認できていること。

フェーズ1: 修正プランの取得

create-review-fix-plan skill を $0 で呼び出し、以下を取得する：

• 未解決レビューコメントの一覧（コメント本文・対象ファイル・行番号）
• CIステータス（失敗ジョブと原因の要約）
• 修正タスクの一覧（目的・対象範囲・完了条件付き）
• タスク間の依存関係

修正点がない場合: gh pr checks $0 でCIの全チェックが Pass していることを確認する。Pass している場合は gh pr merge $0 --merge --delete-branch でPRをマージして終了する。チェックが失敗中の場合はマージせず、CI失敗状況をレビュアーに報告して終了する。

返却内容は後続フェーズで各サブエージェントに渡すため、全文を保持しておくこと。

完了条件: 修正タスクが「並列実行可能なグループ」と「逐次グループ」に分類できていること。

フェーズ2: タスク実行戦略の決定

サブエージェント選定

修正タスク（指摘）ごとに、まず「実装の委任（判断ロジック）」のステップ1〜3で委譲するか直接編集するかを判定する。委譲すると決めたタスクについて、以下の判断軸でサブエージェントを選定し、実行をそのサブエージェントに委任すること

• frontend-implementer: UI/コンポーネント実装、デザイン適用、shadcn/ui等のフロントエンド作業。PencilのデザインデータからUIを実装する（.pen を参照元としてUIに変換する）場合は必ずこのエージェントを使うこと
• pencil-design-updater: Pencilファイル（.pen）自体の編集・更新（要素追加、レイアウト変更、スタイル修正、テキスト差し替えなど）。.pen への編集タスクは必ずこのエージェントに任せること
• lightweight-assistant: 内容が具体的で探索不要・単一ファイル編集レベルの軽量タスク（型定義追加、定数追加、設定ファイル更新など）
• general-purpose-assistant: 上記以外、複数ファイルにまたがる実装、調査を伴うタスク、テスト/Lint修正

並列 vs 逐次の判断

以下のいずれかに該当するタスク同士は 逐次 で実行する：

• 同じファイルを編集する可能性がある
• 一方の出力（型・関数・スキーマ）に他方が依存する
• マイグレーションやスキーマ変更を含む

それ以外は 並列 で実行する。並列実行する場合は、1メッセージ内で複数のAgent tool callを発行すること（順次呼び出しでは並列にならない）。

フェーズ3: サブエージェントへのブリーフィング

サブエージェントは現在の会話履歴を持たないため、起動時は以下を すべて プロンプトに含めること。自己完結したブリーフィングが品質を決める。

【背景】PR #$0 のレビュー指摘対応: <PRタイトル要約>

【あなたが担当する指摘】
<レビューコメント本文を引用>
- 対象ファイル: <path:line>
- 指摘者の意図: <create-review-fix-plan が抽出した要約>

【対象範囲（編集可ファイル/ディレクトリ）】
<具体パスを列挙。範囲外を触らないこと>

【触れてはいけないファイル】
<並列実行中の他タスクが触る予定のファイル>

【完了条件】
- レビュアーの指摘内容が解消されていること
- 該当箇所のユニットテストが追加・更新され、すべてpassすること
- プロジェクトにE2Eテストが存在し、担当する修正がユーザー操作フローに影響する場合: 該当フローのE2Eテストが追加・更新され、passすること（E2Eテストの所在・実行コマンド: <パスとコマンド。存在しない場合はこの行ごと削除>）
- `npm run lint`（またはプロジェクト指定のlint）に該当ファイルでエラーがないこと
- 既存の挙動を意図せず変更していないこと

【スコープ】
上記の指摘を解消する変更だけを行う。範囲外のリファクタ・命名整理・周辺の改善を足さない。気づいた別の問題は修正せず、報告に1行で挙げるだけにする。

【参考情報】
- レビューコメントへの直リンク
- 既存の類似実装の参照先（あれば）

【作業ディレクトリ】
<worktreeの絶対パス>。すべてのコマンドはここを基準に実行すること。

【報告】
指摘をどう解消したか（対象ファイルと要点）・完了条件の充足状況・残課題を簡潔に。埋め草の要約セクションは不要。

サブエージェントが完了報告を返したら、本体側で git diff --stat を実行して変更範囲が宣言通りか検証する。範囲外の変更や指摘と無関係な変更があれば、当該サブエージェントを再起動して修正させる。

フェーズ4: テストとLintの収束ループ

すべてのサブエージェントが完了したら、本体で以下を順に実行：

1. プロジェクトのユニットテストコマンドを実行（package.json の scripts.test を確認）
2. E2Eテストが存在する場合（「E2Eテストの取り扱い（共通ルール）」の判定結果に従う）、E2Eテストコマンドも実行する（scripts の test:e2e / e2e 等）
3. プロジェクトのLintコマンドを実行（scripts.lint）
4. 失敗した場合、「実装の委任（判断ロジック）」のステップ1・2で委譲/直接編集を判定する
   • 委譲する場合: general-purpose-assistant（単一ファイルの自明な修正なら lightweight-assistant）に 失敗ログ全文と該当ファイルパス を渡して修正させる
   • 直接編集する場合: ステップ2の条件をすべて満たすことを確認したうえで Edit で修正する。滑り坂ガード（1件ごとに独立判定・範囲を広げない・3件で以降は委譲へ切替）を必ず守る
5. 修正後、再度テスト（ユニット・E2E）とLintを実行

ユニットテスト/E2Eテスト/Lintコマンドがプロジェクトに存在しない場合はスキップしてよい（その旨を最終報告に含めること）。

フェーズ5: コミットとpush

1. commit-push skill を呼び出し、変更をコミット・push
2. Push後のCI結果は 待たずに 次のフェーズへ進む（CIの収束は別ループで扱う）

フェーズ6: Resolve と description 更新

1. resolve-pr-comments skill を呼び出し、対応済みのレビューコメントをすべてResolveする
2. 今回の修正内容を反映してPRのdescriptionを最新化する
   • gh pr edit $0 --body "<更新後の本文>" を使用
   • 変更点の要約・テスト観点の追記・既存セクションの整合性を保つ
   • ## 修正履歴 セクションを必ず設ける。既存のdescriptionに無ければ末尾に新規追加し、既にあれば追記する形で残す。各エントリは以下のフォーマットに従う:

     ## 修正履歴
     
     ### YYYY-MM-DD: レビュー指摘対応（<件数>件）
     - <対応した指摘の要約1>（対応コミット: <commit hash 短縮>）
     - <対応した指摘の要約2>（対応コミット: <commit hash 短縮>）
     

     • 日付は date +%Y-%m-%d で取得した実行日を使用する
     • 過去のエントリは削除・改変せず、新しいエントリを上に追記する（新しいものが上）
     • 1件ごとに「何を指摘され、どう直したか」が読み手に伝わる粒度で書く
3. 最終報告として、対応した指摘の件数とPRのURLを出力する。あわせて以下のフォーマットで自己監査結果を必ず含める（「実装の委任（判断ロジック）」の適用状況をセッション自身で振り返るためのもので、判定の正当化より事実の記録を優先する）

   ## 実装委任の自己監査
   - 起動したサブエージェント: <エージェント名 × 件数。例: general-purpose-assistant × 2, lightweight-assistant × 1>
   - メインエージェントによる直接編集: なし / あり（<件数>件）
     - <対象ファイル>: <変更行数> / <判定根拠。ステップ2の1〜5をどう満たしたか>
   

   直接編集が「あり」の場合は、ステップ2のどの条件で許容されたのかを件ごとに1行で書く。ステップ1に該当していたのに直接編集した場合は、その事実をそのまま記録する（隠さない）

PRクローズ時の連動処理（共通ルール）

実行中に何らかの理由でPRをクローズする判断に至った場合（例: 指摘が別アプローチでの再実装を求めている、要件の陳腐化、別PRで対応済み、コンフリクト解消不能など）は、PRと 関連Issueを必ず連動してクローズする。PRだけ閉じてIssueをOPENのまま残すと他の作業者が同じスコープに重複着手するため、片側だけのクローズは禁止する。クローズ判断はフェーズ0の安全ガードとは独立に発生し得るため、判断時点でこのルールを適用すること。

手順:

1. クローズ理由を1-3行で言語化する
2. PRに理由を含むコメントを投稿し、PRをクローズする

   gh pr close $0 --comment "<クローズ理由。代替PR/Issueがあればそのリンクを含める>"
   

3. 関連Issueを特定する。優先順位:
   • gh pr view $0 --json closingIssuesReferences -q '.closingIssuesReferences[].number'（GitHubが自動認識したリンク）
   • 上記が空の場合は gh pr view $0 --json body -q '.body' の本文から Closes #<n> / Fixes #<n> / Resolves #<n> を正規表現で抽出する
4. 取得した各Issue番号について gh issue view <n> --json state -q '.state' で状態を確認し、OPEN の場合のみ以下を実行する。

   gh issue comment <n> --body-file - <<EOF
   ## 関連PRクローズに伴うクローズ
   PR #$0 を以下の理由でクローズしました。本Issueの作業はこのPR内では行いません。
   
   ### クローズ理由
   <理由>
   
   ### 今後の扱い
   <代替PR/Issueがあればリンク。再着手が必要な場合はその旨と新規Issue番号>
   EOF
   gh issue close <n> --reason "not planned"
   

5. 最終報告に「PR #$0 とリンクされたIssue # をクローズした理由・代替手段」を必ず明記する

注意事項

• 修正の委譲判定を指摘ごとに行う: 「実装の委任（判断ロジック）」のステップ1に1つでも該当すれば委譲、ステップ2の全条件を満たす場合のみ直接編集、判定が割れたら委譲側に倒す。直接編集は滑り坂ガード（1件ごとに独立判定・範囲を広げない・3件で以降は委譲へ切替）付きでのみ許される
• デフォルトブランチで作業しない: フェーズ0で必ず確認。ファイル編集前の pwd 再確認を推奨
• サブエージェントの結果を鵜呑みにしない: 完了報告は「やったつもり」を示すだけ。git diff で実際の差分を必ず検証する
• 指摘の本質に応える: 字面だけ拾って小手先で済ませず、レビュアーの懸念の根本（設計・安全性・可読性）に向き合う
• コメントは残さない: 生成コードに「なぜ」を説明する以外のコメントを入れないよう、サブエージェントへのブリーフィングにも明記する
• エラーの根本原因に向き合う: テスト失敗を --no-verify やテストのスキップで誤魔化さず、原因を特定してから修正する
• E2Eテストを置き去りにしない: E2Eテストが存在するプロジェクトでは、「E2Eテストの取り扱い（共通ルール）」に従い、ユーザー操作フローに影響する修正に対して該当フローのE2Eテストの追加・更新まで完遂する。ユニットテストのpassだけで完了扱いにしない
• ユーザーへの確認を求めない: 安全ガード（フェーズ0のworktree外/デフォルトブランチ検出、PRがCLOSED/MERGED）に該当する場合のみ中断し、それ以外は既定挙動に従って自律的に最後まで完遂する
• PRクローズと関連Issueクローズは必ずセット: 「PRクローズ時の連動処理」を必ず適用し、関連Issueも理由付きコメントを残してクローズする