scope-creep-detector

スコープ逸脱検出器

1 行の修正のために、レビュー担当者が 3 つのサブシステムにまたがる 14 個のファイルをリバースエンジニアリングする必要があってはいけません。このスキルは、git の差分と明示された意図を比較し、スコープに関するシグナルを提示して、変更を維持、分割、または理由を説明するという判断につなげます。

すべてローカルで実行されます。スクリプトはネットワーク接続を行わず、作業ツリー、インデックス、コミット、ブランチを変更しません。

使用するタイミング

• 差分が意図した範囲を超えて広がっている可能性のあるプルリクエストを作成する前
• バグ修正で予想外のファイルやサブシステムに変更が及んでいるとき
• ステージ済みの変更が広範すぎないかユーザーから尋ねられたとき
• 差分に依存関係、公開 API、設定、CI、またはビルドの変更が含まれているとき
• 複数の変更が混在している場合に、具体的な分割計画をユーザーが求めているとき

使用しないタイミング

• コードのフォーマット、リンターの実行、またはコミットメッセージの作成
• 合意済みのスコープ内での正確性、セキュリティ、またはテスト品質のレビュー
• 多数のコミットにわたるプロジェクトの過去の成長状況の測定
• ユーザーの承認を得ずにファイルを編集または元に戻すこと

意図を確認する

ユーザーから 1 行の意図が示されている場合は、それを使用します。fix null dereference in parser や add retry limit to webhook delivery のように、具体的な内容にしてください。

意図が示されていない場合、スクリプトは現在のブランチ名を代わりに使用します。その名前が一般的なもの、detached 状態のもの、または作業内容と無関係なものであれば、関連性を判断する前に、意図を 1 行で尋ねてください。

分類器を実行する

このスキルのディレクトリから実行し、--repo に対象リポジトリを指定します。

作業ツリーの差分：

python3 scripts/scope_creep.py --repo /path/to/repo \
  --intent "fix null dereference in parser" --json

ステージ済みの差分：

python3 scripts/scope_creep.py --repo /path/to/repo --staged \
  --intent "fix null dereference in parser" --json

マージベースとの差分：

python3 scripts/scope_creep.py --repo /path/to/repo --base main \
  --intent "fix null dereference in parser" --json

保存済みの差分または標準入力：

python3 scripts/scope_creep.py --diff change.diff --intent "parser fix" --json
git diff --staged | python3 scripts/scope_creep.py --diff - \
  --intent "parser fix" --json

--hunk-threshold を使用するのは、リポジトリにデフォルトの変更量しきい値を変える根拠が文書化されている場合に限ってください。警告を消すためだけにしきい値を調整してはいけません。

JSON を解釈する

推奨事項を示す前に、references/scope-signals.md を読んでください。分類器の結果はトリアージの根拠として扱い、作成者の意図を証明するものとは見なさないでください。

• in_scope：意図とパスのキーワードが少なくとも 1 つ重複するファイルパス
• likely_creep：重複がないパスと、その理由および検出されたシグナル
• new_deps：対応しているマニフェスト形式で追加された依存関係
• api_renames：近接した位置にある、削除された宣言と追加された公開関数またはクラスの宣言
• config_edits：CI、コンテナー、ビルド、YAML、TOML の変更
• stats：変更量、サブシステム数、大きすぎるハンク、フォーマットのみのファイル

空の配列も根拠になります。シグナルが検出されなかったと伝え、差分が確実にスコープ内だとは言わないでください。

維持、分割、または理由を説明する

likely_creep の各項目に、次のいずれかの判断を割り当てます。

1. 維持：パスが明示された意図に必要で、つながりが直接的な場合。つながりを 1 文で説明します。
2. 分割：独立して取り込める場合、別のサブシステムに属する場合、または意図に不要な依存関係、API の名前変更、設定変更、大きなハンクを導入する場合。後続の変更に含めるファイルまたはハンクを明記します。
3. 理由を説明：横断的な編集を安全に分離できない場合。それを必要とする不変条件またはビルド上の制約を示し、レビュー上のリスクを明記します。

根拠が曖昧な場合は、分割を優先してください。重複スコアが 0 だからといって、そのファイルが無関係だと断定してはいけません。パスに含まれる語彙は、簡易的で決定論的な代替指標です。

スコープレポートを作成する

次の簡潔な構成を使用します。

1. 意図と差分の取得元
2. 変更されたファイルとサブシステム、および追加・削除の合計
3. スコープ内の変更
4. シグナルの根拠を添えた、スコープ逸脱の可能性が高い変更
5. 維持、分割、または理由を説明するための表
6. 必要に応じて、提案する後続作業のグループ分け

ファイルパスとハンクヘッダーを明記します。大きな混在ハンクについては、スクリプトで自動的に分割できないことを説明し、最小限のまとまりのある編集内容を示します。分割、取り消し、ステージング、またはコミットを実行する前に、必ず確認を求めてください。

ファイル

• scripts/scope_creep.py：決定論的な unified diff パーサーおよび分類器
• references/scope-signals.md：シグナルの定義、しきい値、制限