pr-improver

PR 改善ツール

/code-improver:improve を実行して現在のブランチを改善します。これは、レビューで重大または大きな指摘がなくなるまで、PR レビュアーと修正サブエージェントをブランチの変更に対して繰り返し実行する動的ワークフローです。ループ、その記録簿、ガードはワークフロー内にあり、このスキルはブランチの差分から対象範囲を特定し、結果を伝えます。

ループの開始

ユーザーが指定した値：$ARGUMENTS（空の場合は、会話からベースブランチと設定を取得します）。

1. ブランチと変更対象の範囲を特定する

1. リポジトリのルート：git rev-parse --show-toplevel。リポジトリ外では明確なエラーを出して終了します。
2. ベースブランチ：引数が指定されていればその値、指定されていなければリポジトリのデフォルトブランチ（git symbolic-ref refs/remotes/origin/HEAD → 短縮名。取得できない場合は main）。現在のブランチがベースブランチそのものの場合は、改善する差分がないため実行を拒否します。
3. 変更ファイル：git diff --name-only <base>...HEAD。空の場合はその旨を伝えて終了します。
4. 対象範囲：変更ファイルのディレクトリ。ファイルごとの glob は対象が狭すぎます（PR の修正では、変更されたコードの隣にテストを追加することが適切な場合があります）。各変更ファイルを、リポジトリ相対のディレクトリ glob <dir>/** に対応付けます（ルートにあるファイルが変更された場合に限り、リポジトリのルートで ** を使用します）。その後、重複を取り除き、別の glob に包含される glob を除外します。

2. ループスクリプトを特定する

ループは、このプラグインにある動的ワークフロー workflows/improve.js です。パスを指定して起動します。scriptPath には解決済みの絶対パスが必要です。また、Workflow ツールの name は組み込みワークフローとプロジェクトのワークフローを解決するため、マーケットプレイスからインストールしたワークフローでは code-improver:improve で見つからないことがあります。次の順に試し、最初に見つかったものを使用します。ホームディレクトリを . より先に検索するため、マーケットプレイスからインストールしたコピーが、このマーケットプレイスのチェックアウトより優先されます。

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"（代わりにこの変数が設定されている場合）
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

表示されたパスをそのまま使用します。プラグインディレクトリは、そのパスから /workflows/improve.js を取り除いたものです。これを pluginRoot とします。3 つすべてでパスが見つからない場合は、{name: "code-improver:improve"} を一度だけ試します。それも利用できない場合は、ループを特定できなかったと伝えて終了します。パスを手作業で組み立てたり、ループを独自に実行したりしないでください。

3. ワークフローを実行する

Workflow ツールで実行します。{scriptPath: "<the path from step 2>", args: {...}}：

{
  "target": "<repo root>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Review the working tree's changes against <base> as a pull request: correctness, tests, error handling, and the review dimensions the skill prescribes."
  },
  "scope": ["<derived-dir-glob>/**"],
  "pluginRoot": "<the plugin directory from step 2>",
  "maxRounds": 5
}

• reviewer — 上記のデフォルト設定では pr-review-toolkit プラグインが必要です。ユーザーが別の PR レビュアー（スキルまたはエージェント）を指定した場合は、それを使用し、kind を適切に設定します。
• maxRounds は、ユーザーが別の上限を指定した場合にのみ設定します。
• pluginRoot を指定すると、実行時にメトリクスコレクターを検出できます。手順 2 がワークフロー名にフォールスルーした場合に限り、このキーを省略します。その場合、ワークフローは自身を検索します。
• finalize のデフォルト設定は PR に適しています。ブランチがプラグイン内にある場合を除き、バージョンは更新せず、ナレーションの削除とドキュメントのパスは有効のままにします。
• decision は、継続する場合にのみ設定します（下記参照）。

ループのベースラインスナップショットは、ループ開始時のツリーです。スコープガードはブランチの未コミットの変更を保護し、レビュアーがレビューするのは PR 自体のコミットです。

ワークフローはバックグラウンドで実行され、見守る必要はありません。レビュー、修正、再レビューを行い、修正ラウンドごとにスコープを確認し、レビューに問題がない場合にのみ完了します。コミットは行われず、すべての変更は作業ツリーに残ります。

Workflow ツールを利用できないか、実行を拒否された場合は、停止してその旨を伝えてください。 直接編集してループをその場で再現しようとしてはいけません。台帳、スコープガード、エスカレーションの保証はワークフローにあり、その場での模倣にはありません。

結果が halted: "reviewer-unavailable" の場合は、その旨を伝えて停止してください。 このセッションにはレビュアーがインストールされていません。どのプラグインが提供しているか（デフォルトでは pr-review-toolkit が必要）をユーザーに伝え、インストール後に再実行してください。自分でブランチをレビューしてはいけません。

ループの実行中にターンを終了してはいけません。 Workflow ツールはタスク ID をすぐに返し、結果は後から届きます。対話型セッションでは完了通知によって再度呼び出されるため、それを待ってください。非対話型の実行（スクリプト、CI、評価）では次のターンがありません。停止するとループのラウンド途中で放棄されるため、起動後は完了するまでタスクをポーリングしてください（返されたタスク ID を使った TaskOutput、またはスリープして再確認）。「ループが実行中です。後で報告します」と応答すると、実行が放棄されます。

結果の報告

ワークフローは構造化された結果を返します。違いは重要なので、正確に報告してください。

• converged: true — 最後のアクションは、重大または大きな指摘がゼロのレビューです。使用したラウンド数、残っている軽微な指摘（open_minor_count）、成果物のパス（ledger_path、metrics）を報告します。
• capped: true — 修正予算が尽き、最終レビューでもブロッキング問題が見つかりました。上限に達したため、収束していませんとはっきり伝え、open_blocking を列挙してください。成功として提示してはいけません。
• escalation — ループが収束していないことを検出しました（指摘の再発、件数が減らない、修正による問題の移動など）。エスカレーションのメッセージと指摘 ID をユーザーに伝えてください。これは追加ラウンドではなく、設計上の判断が必要です。
• halted — ガードが発動しました（スコープ違反、新規ファイルの未登録、レビュアーの終了または利用不可、あるいは finalize パス自体の変更が後続チェックに失敗した場合）。violations／new_untracked_files のパス、finalize_regressions の箇所、メモを伝えてください。
• notes は常に結果とともに返されます。必ずユーザーに伝えてください。「git リポジトリが初期化されました」といった重要な警告が含まれます。

エスカレーション後の継続

ループは設計上、エスカレーション時に停止します。ユーザーが判断した後、同じ引数に次を追加して新しい実行を開始します。

{ "decision": "<the user's ruling, verbatim>" }

新しい実行ではディスク上の台帳が再読み込みされるため、すべての指摘、却下、判定が引き継がれます。ラウンド数はリセットされますが、再導出は行われません。

実行中のループを停止するには、ワークフロータスクを停止します（TaskStop）。ディスク上の台帳は最後のラウンド時点の状態になっており、再実行するとそこから再開します。

使用しない場合

• 一度限りのレビュー：PR-review スキルを直接実行してください。このループの価値は反復にあります
• スキルの場合：skill-improver エントリを使用してください。適切なレビュアーを設定します
• プッシュ前の探索的な作業：レビューと修正のループは差分を仕上げますが、作業の方向性が定まっていない段階では、手動で反復するほうがより細かく制御できます