fresh-eyes-sweep

Fresh Eyes Sweep

スラッシュまたはドル記号による呼び出しですでにこれらの指示が会話に追加されている場合は、そのまま従ってください。 その場合、このスキルをスキルツールで再度呼び出さないでください。

指定された Git 範囲を調べ、証拠に裏付けられた誤りを確認します。安全に修正できる問題はすべて修正してください。対象となる各ファイルを漏れなく確認してください。 検証済みの変更なしと判断するには、対象範囲を確認し、全体を一巡して新たな問題が見つからないことが必要です。問題のない作業には手を加えないでください。確認を正常に完了したことを示すために、編集を行う必要はありません。

--max-runtime DURATION は任意です。45m や 3h のように、正の整数の後に m または h を付けて指定します。無効な期間、不明なオプション、または曖昧な位置引数は拒否してください。期限が指定された場合は、監査を始める前に期限を計算してください。その場合、最後の15％を全体の検証と報告に充てます。ただし、確保する時間は5〜30分の範囲内とし、実行時間の合計を超えないようにしてください。その時間帯になったら、進行中の作業を完了し、新たな修正には着手しないでください。期限を超過するのではなく、台帳を添えて未完了の確認として報告してください。

Overnight Autonomy

呼び出し時に、環境のローカル時刻を確認してください。22:00を過ぎているか、08:00より前である場合は、その後に時間帯が変わっても、実行全体を自律的に進めてください。22:00ちょうどと08:00ちょうどは、この時間帯に含まれません。

夜間の自律実行中は、次のとおりです。

• ユーザーに質問したり、確認、選択、承認を求めて作業を中断したりしないでください。ただし、これによってスキルの権限が拡大するわけではありません。破壊的な操作、情報開示、購入、公開契約、その他承認が必要な操作は実行しないでください。
• 最も安全で元に戻しやすい解釈を採用し、独立して進められる作業を続行してください。曖昧な点、阻害要因のある問題、承認が必要な選択はすべて夜間の保留項目に記録し、実行を中断しないでください。
• 終了時に、各項目の根拠、安全な対応、影響、必要な判断を添えて保留項目を提示してください。質問ではなく、指摘事項として記述してください。保留項目がない場合、このセクションは省略してください。

Ledger Interface

この SKILL.md から scripts/sweep-ledger.py の場所を解決してください。リポジトリの外に一時台帳を作成してください。

uv run "<skill-dir>/scripts/sweep-ledger.py" init \
  --root <repo> --ledger <scratch.json> [<path>...]

パスを指定せずに init を実行すると、リポジトリ全体が対象になります。パスを指定すると、その Git 範囲だけが対象になります。追跡対象のファイルにも無視対象外の未追跡ファイルにも一致しないパスを指定すると、init は失敗します。このコマンドは、追跡対象のファイルと無視対象外の未追跡ファイルをすべて記録し、各パスの実行前のワークツリー状態も記録します。このヘルパーは、生成物、ベンダー提供ファイル、バイナリ、安全なファイル、重要なファイル、問題のあるファイルを分類しません。

パスを調査するか、その他の方法で確認した後に限り、エージェントの判断をアトミックに記録してください。

uv run "<skill-dir>/scripts/sweep-ledger.py" mark \
  --ledger <scratch.json> --status <pending|inspected|fixed|reported|excluded> \
  --path <path> [--path <path>...] [--reason <text>]

excluded には、エージェントが記述した理由が必要です。不明なパスや無効なバッチを指定すると、部分的な更新も行わずに失敗します。並行実行される mark 呼び出しは、サイドカーの <scratch.json>.lock によって直列化されるため、並列サブエージェントがそれぞれのパスを記録できます。

uv run "<skill-dir>/scripts/sweep-ledger.py" pending --ledger <scratch.json> [--limit <n>]
uv run "<skill-dir>/scripts/sweep-ledger.py" summary --ledger <scratch.json>

pending は、まだ確認されていない次のパスを安定した順序で返します。summary は、ステータスの正確な件数、実行前からの編集件数、完了状況、パーセンテージの入力値、10セルのバーを返します。これらの値をそのまま使用してください。進捗を推定したり、台帳の計算を独自に再実装したりしないでください。

セットアップ

1. Git を必須とし、適用されるリポジトリの指示を確認します。ワークツリーのルート、開始時のコミット、開始時のステータス、確定した対象範囲、期限と検証期間を記録します。

2. 指定された対象範囲の台帳を初期化します。エージェントは、その対象範囲を把握するために必要な共有設定や指示を追加で確認できます。台帳の範囲を黙って広げないでください。init によって約 2,000 ファイルを超えるファイルが割り当てられ、ユーザーが [paths] を指定していない場合は、ファイル数だけを理由に質問せず、割り当てられた台帳を、上限を設けたシステムを考慮したディレクトリまたはサブシステムのスライスに分割して続行します。要求された対象範囲全体を台帳に保持し、システムマップと集約検証を通じて、スライス間の不変条件を維持します。

   指定された期限内にすべてのスライスを完了できない場合は、検証期間の終了時点で停止し、再開可能な残作業の開始点を報告します。重要な不変条件を維持できる安全な分割方法がなく、ユーザーがより狭い範囲を選択する必要がある場合に限り、質問します。自律的な夜間実行中は、その選択を夜間バックログに記録し、独立して安全に進められる作業をすべて完了します。

3. 生成物、ベンダー提供物、ミニファイ済みファイル、バイナリ、大量データのアーティファクトを分類します。1 行ずつ確認するのが適切でない場合は、生成元、スキーマ、または不変条件に基づいて検証し、エージェントの理由を添えて記録します。

4. 実行可能なエントリーポイント、ワークスペースまたはパッケージ間の依存方向、公開インターフェース、ジェネレーターと派生アーティファクト、外部データおよび永続化データとの境界、各重要な不変条件の担当者をまとめた簡潔なシステムマップを作成します。スライスを選ぶ前に、最もリスクの高いワークフローを端から端まで追跡します。

5. 直近の履歴と差分を確認し、特に最新の変更から、影響を受ける呼び出し元、依存関係、テスト、設定、ドキュメントを特定します。根拠に基づいてスライスと修正の優先順位を付けます。正確性、データ損失、セキュリティ、外部に公開される個人データや情報開示のリスクを優先します。信頼性、保守性、測定済みのパフォーマンス、開発者エクスペリエンスは、これらの問題より後に順位付けします。変更の新しさは優先順位を決める指標の 1 つとして扱い、網羅性の代わりにはしません。

6. ビルド、テスト、リント、型チェック、フォーマット、コード生成のチェックを特定します。

7. 最初の修正に着手する前に、安全で関連性のあるすべてのチェックのベースラインを確立します。失敗した場合は、再現可能な失敗を裁量で行う作業より優先します。不明確または禁止されている操作を必要とする失敗は保留しつつ、独立して検証できる作業を続けます。

8. 台帳に記録された既存の編集をすべて保持します。元に戻したり、取り込んだり、コミットしたり、指摘事項として報告したりしないでください。

マッピング後、### 🔎 Sweep mapped — <files> files · <slices> slices · ledger <scratch.json> を報告します。スライス数は整理のためにエージェントが決定します。ファイル数は台帳から取得します。

台帳はセッション終了後も保持されます。後続のセッションでは、init を再実行せず、同じ台帳のパスを指定して同じスイープを再開します。pending が残作業の開始点を示し、すでに記録済みのパスは再確認しません。すべての進捗報告に台帳のパスを含め、スイープが未完了の場合は、ユーザーが次のセッションに引き継げるよう、完了報告でも台帳のパスを再度明記します。

サブエージェント

• 対応範囲や完了までの時間が実質的に改善される場合は、独立した作業範囲を委任します。ホストの上限とユーザーの委任に関する希望の範囲内で、必要最小限のチームを編成します。
• ホストがモデルを選択できる場合は、タスクに応じてレビュアーと修正担当者のモデルを慎重に選択します。それ以外の場合は、ホストのデフォルトを使用します。
• エージェントを起動する前に、エージェント数と各グループのモデルを1行で示し、予定している並列実行を告知します。
• ユーザーが上限を引き上げない限り、同時に実行するレビュアーは4人以下とし、常にホストの同時実行数の範囲内に収めます。
• 起動した各タスクの ID をコーディネーターの作業範囲計画に記録し、後から停止要求があった際に実際の ID に対応できるようにします。台帳の reason には、除外理由のみを記録します。
• 執筆エージェントには、固定 ID、依存関係の順序、重複しない厳密な書き込み範囲、リポジトリの制約、必要な完了証跡を指定します。各スライスの指示には、書き込み範囲内の言語に適用される厳格な静的チェックゲート（型チェック、リンティング、フォーマット／インポート順序）をすべて含め、ツールで可能な限り範囲を絞って実行するよう求めます。リポジトリ全体に適用される各チェックゲートは、影響を受けるスライスが確定した後、1人の検証担当者に割り当てます。他のエージェントは重複して実行せず、その依存関係を報告します。共有マニフェスト、ロックファイル、エクスポート、統合ファイルは、1人の担当者に順番に割り当てます。
• 依存する作業を開始する前に、各ウェーブの結果をすべて照合します。並行処理、セキュリティ、スライス間の不変条件など、独立した精査によって具体的なリスクに対処できる場合は、コンテキストを新たにした検証担当者を起用します。通常の編集だけであれば、検証担当者は不要です。
• サブエージェントとワーカーはコミットしません。コーディネートセッションが確定済みのスライスを順番にチェックポイントコミットするため、Git インデックスに触れるプロセスは常に1つだけになります。
• 1つのセッションが保持できるコーディネーション要求は1つで、新しい要求を出すと以前の要求は置き換えられます。リポジトリで ai-coord のような要求ベースのコーディネーターを使う場合、書き込みエージェントを起動する前に、進行中のすべての書き込みスライス（実行中のエージェントとコーディネーター自身の編集）の和集合を要求します。まだ書き込み中のスライスを除外せず、新しい和集合に範囲を広げます。進行中のすべてのスライスの照合とコミットが終わるまで、要求を解放しません。
• チェックポイントコミット中に lint-staged などのフックが失敗した場合、ここでインデックスの競合を診断するのではなく、$commit の失敗時の復旧ガイダンスに従います。

調査と修正

実装、呼び出し元、テスト、設定、ドキュメントをまとめて把握できるよう、関連する作業範囲ごとに進めます。各スライスでは、まず根本から考え、ユーザーの依頼とリポジトリの根拠に基づいて、意図する成果と必要な動作を特定します。現在の実装を前提条件とせず、その妥当性を検証します。次の順序で検討します。

1. 何が不要で、過度に複雑で、または根拠の弱い仮定に基づいていますか？根拠に照らして、その仮定を疑います。
2. 必要な動作と契約を維持したまま、完全に削除できるものは何ですか？不要と判断する前に、利用箇所と不変条件を確認します。
3. 不要な要素を削除した後、残ったロジック、インターフェース、ワークフローのうち、簡素化できるものは何ですか？

簡素化より削除を、最適化より簡素化を、自動化より最適化を優先します。依頼された範囲内で、確認済みかつ安全な改善を適用します。この順序は、要件を削除したり、不要な作業を自動化したりする理由にはなりません。

重要な制御、データ、並行処理、エラーの経路を、最初から最後までたどります。具体的なバグ、見落とし、無効な前提、未処理のエッジケース、セキュリティ／信頼性の問題、不整合、重複、デッドコード、古いドキュメント、不要な複雑さを探します。また、性能、依存関係、データ形式と拡張機能、設定、可観測性、アクセシビリティ、エージェントのコンテキスト、命名、ディレクトリ構成について、根拠のある問題も調査します。スタイル上の好みや、検証されていない推測は指摘事項に含めません。

該当する外部データおよび永続化データとの境界では、次の点を調査します。

• 検証、ドメインの精度、単位。
• 順序の決定性と重複排除。
• 冪等性と繰り返し実行時の動作。
• 原子性と中断への安全性。
• 再試行とページネーションの完全性。
• 同時実行数の制限、キャンセル、リソースのクリーンアップ。
• シークレット、ログ、パス、一時ファイル、コマンドの安全性。

編集前に各問題を確認してください。意図が明確で検証手段がある場合は、根本原因を最小限の変更で修正してください。既存のカバレッジにない重大な障害モードを防ぐ回帰テストを追加してください。自明なテストや、元に戻せる文章・設定の変更をなぞるだけのテストは追加しないでください。対象範囲内の検証可能なリスクは、報告の前にすべて修正してください。残存リスクとして報告してはいけません。

reported とするのは、実際の判断が必要な場合に限ってください。意図が曖昧な場合、リポジトリ外の利用者に対する公開契約を安全に修正できない場合、または検証手段がない場合です。reported にした指摘にはすべて、推奨する修正とその影響範囲を記載してください。推測に基づく機能、広範なリファクタリング、見た目だけの変更は追加しないでください。

1000 行を超えるソースファイルと、2000 行を超えるテストファイルは、調査候補としてのみ扱ってください。凝集度、結合度、変更リスク、またはテスト容易性からより適切な分割点が明らかな場合に限り、ファイルを分割してください。行数だけでは根拠になりません。確認済みの構造上の問題にインターフェースや分割点の再設計が必要な場合は、利用できるなら $codebase-design を使用してください。不変条件はそれを所有するモジュールに集約し、中継するだけのモジュールには削除テストを適用してください。動作が実際に異なる箇所に限って分割点を導入し、呼び出し側とテストは変更後のインターフェースを使用してください。

インターフェース、永続化形式、エクスポート名、またはパスを変更する前に、すべての生成元、利用側、スキーマ、フィクスチャ、ジェネレーター、エクスポートまたはマニフェスト、スクリプトまたはレシピ、チェック、設定参照、文書を列挙して移行してください。変更後は古い識別子を検索し、意図して残した箇所をすべて説明してください。依存関係やフレームワークの更新、データ形式や拡張子の変更、改名、再編成は、移行が原子的であり、互換性を実証でき、リポジトリのチェックで検証できる場合に限って適用してください。ベースラインの指標と再現可能なベンチマークを記録していない性能変更は維持しないでください。

実験が根拠の基準を満たさない場合は、その実験に起因する変更だけを元に戻してください。リポジトリ全体に対するクリーン、チェックアウト、リセットのコマンドは使用しないでください。重要でない変更のまとまりごとに、利用できるなら、そのまとまりで変更されたファイルの正確な集合を対象として $code-polish を実行してください。それ以外の場合は、同じ固定範囲のルールをその場で適用してください。つまり、理解しやすさまたは欠陥リスクが測定可能な形で改善される場合に限って単純化し、重大度順にレビューし、根拠のある欠陥を修正し、最も狭い範囲で検証できるチェックを再実行してください。

長時間の作業では、まとまりのある作業単位が完了した後にのみ進捗を共有し、台帳の概要に記載された正確な進捗バーと件数を使用してください。進捗バーが示すのはパスの確認状況であり、調査の深さではありません。

テスト

テストもコードと同じく、第一原理に基づいて見直し、同じかそれ以上の不具合を検出できる、より小さなテストスイートを目指します。各テストがどの必須動作を保護しているかを特定したうえで、次の対応を行います。

• トートロジー的なテストを削除します。テスト対象のコードに起こり得る不具合があっても、構造上必ず成功するテストです。典型例は次のとおりです。

  • モックやフィクスチャに設定した値そのものを検証する。
  • テスト対象のコード、またはそのロジックを複製したコードで期待値を導出する。
  • 定数、型、リテラルがそれ自身と等しいことを検証する。
  • 言語、フレームワーク、依存関係の動作を言い換えて検証する。

  手早く確認するには、実装に不具合があると仮定して考えてください。それでもテストが成功するなら、トートロジー的です。

• 古くなっている、または役に立たないテストを削除します。モックやフィクスチャだけで維持されている、削除済みまたは名称変更済みの動作を対象とするテスト、意味のあるアサーションがないテスト、要件に依存しない付随的な実装の詳細や呼び出し順序を固定するテスト、実行されていない理由が現存しないままスキップまたはコメントアウトされているテストが該当します。

• 実質的に同じことを証明するテストを統合します。入力だけが異なる同一の経路は、テーブル駆動テストまたはパラメーター化テストにまとめます。別のテストのアサーションで完全に網羅される、より限定的なテストは削除します。ファイル間で重複するテストは、所管するテストスイートにまとめます。

削除または統合する前に、保護対象の動作が不要になっているか、名前を特定した保持対象のテストで引き続きカバーされているかを確認してください。重複が明らかでない場合は、カバレッジ出力を使うか、対象のコードに一時的に不具合を入れて確認します。

統合後も、固有のアサーション、入力、原因を特定できる失敗メッセージをすべて残します。修正済みの不具合に対する回帰テストは、別のテストで同じケースが明確にカバーされていない限り保持します。チェックを通すために、失敗するテストや不安定なテストを削除またはスキップしてはいけません。原因を修正するか、reported と記録します。影響を受けるスイートを変更の前後で実行し、テスト数の増減を記録します。

コメント

すべてのコメントを、それが説明するコード、呼び出し元、履歴と照らし合わせて確認します。コメントの修正は、明確に STALE（コードに存在しなくなった動作を説明している）、ORPHANED（存在しないシンボル、パス、フラグ、または概念を示している）、MISLEADING（実際とは実質的に異なる動作を示唆している）、または REDUNDANT（意図、制約、背景を示さず、自明なコードを説明している）場合に限ります。正しい内容を証拠で確認できた場合は、コメントを書き直します。それ以外の場合は削除します。コメントに合わせるためだけに実行可能なコードを変更してはいけません。また、有用な根拠や、表現に不完全さがあっても正確なコメントはそのまま残します。

動作に影響するコメントはコードと同様に扱います。コンパイラーやツールの指示（//go:*、ビルド制約、cgo の前置宣言、go:embed、@ts-expect-error、リンターの抑制、カバレッジプラグマ）、ライセンスヘッダー、公開 API のドキュメント、並行性、所有権、安全性に関する契約が該当します。ツールの意味を証明し、関連するツールで検証した場合に限り編集します。それ以外の場合は reported と記録します。

検証と報告

各修正を証明できる最小範囲のチェックを実行します。変更したファイルに該当する、発見されたすべての型チェック、リンティング、フォーマット／インポート順序のゲートを含め、その後、変更したファイルに対象を絞ったチェックをまとめて実行します。影響を受けるパスを再確認し、新たな根拠のある問題が見つからなくなるまで繰り返します。完了を宣言する前に、スイープによる追加分も含め、結果に照らして第一原理からの問いを見直します。チェックに合格しただけでは、不必要な複雑さは正当化されません。

指定された期限の検証期間中は、自分が担当する編集内容を整合させ、最終的な変更ファイルの集合に照らして妥当な、フォーマット、リンティング、型、テスト、ビルド、不変条件の各チェックをまとめて実行します。最終結果を記録済みのベースラインと比較します。完了を宣言する前に、カバレッジ、修正内容、チェックをツールの出力と照合します。

スイープによってコミットがプッシュされ、リポジトリに .github/workflows などの CI ワークフローが定義されている場合は、報告前にプッシュしたコミットの実行状況を確認します（gh run list --commit <sha>、続いて gh run watch <run-id>。ホストが対応している場合はバックグラウンドで実行します）。この場合、スイープに起因する失敗を修正し、CI の結果を報告します。変更したコードの動作がプラットフォームごとに異なり、ローカルチェックが 1 つのプラットフォームしか対象としていない場合は、未検証のプラットフォームをリスクとして明記します。

helper の complete が true の場合に限り、先頭に ### ✅ Sweep ledger complete — <accounted>/<mapped> files accounted (<inspected> inspected, <excluded> excluded) を記載します。それ以外の場合は、### ⛔ Sweep incomplete を使用します。修正済み、報告済み、除外済みの件数とチェック数をまとめます。また、削除および統合したテストについて、テスト数の差分を記載します。コメントの修正数がゼロ以外の場合は、その数も記載します。Check | Baseline | Final の簡潔な表、変更した成果物と検証済みの修正内容、サブエージェントの結果も含めます。

reported の各指摘は Open 項目として扱います。Open 項目で根拠として挙げてよいのは、ユーザー所有の入力、リポジトリ外での操作、または確認が必要な境界（破壊的な操作、購入、デプロイ、外部への書き込み）に限ります。タスクで書き込みが許可されており、リポジトリ内の変更で項目を解決できる場合は、既定のメンテナンス権限のもとで、報告前に変更を行います。一般的なエンジニアリング上の判断に対して、needs owner decision、report-only、residual risk と書いてはいけません。判断して変更を行い、その判断を報告します。

該当する場合は、失敗を示す証拠とともに差し戻した実験、証拠・推奨する修正・影響範囲を添えた reported の各指摘、該当する場合は夜間対応のバックログも含めます。### ⛔ Sweep incomplete の場合は、次のセッションが pending から再開できるよう、台帳のパスを記載します。スクラッチ台帳の内容、無関係な既存の変更、大量のデータをそのまま載せてはいけません。報告を実質的に裏付ける場合は、タスクに関連する証拠を含めます。

インタラクティブな実行（夜間対応ではない実行）で reported の指摘がある場合は、最後に、推奨どおりすべて修正するか、特定の項目を選ぶか、報告済みのままにするかを尋ねる決定質問を 1 つ記載します。「問題をすべて／何でも修正して」や「判断は任せます」など、呼び出し時の文言ですでに修正が承認されている場合は、質問を省略します。ただし、破壊的な操作、外部への書き込み、購入については、呼び出し時の文言にかかわらず、明示的な確認が必要です。承認後は、同じスイープのルールに従って承認された項目の修正フェーズを実施します。確認、修正、検証、台帳の更新を行い、$code-polish を再実行したうえで、更新した台帳とチェック結果を報告します。自律的な夜間実行では質問を省略し、reported の指摘は夜間対応のバックログに残します。

完了には、マッピングされたすべてのパスが確認済みであること、すべての指摘が修正・検証済み、承認された修正フェーズで修正済み、または証拠と保留中の判断を添えて報告済みであること、そして関連するすべてのチェックに合格するか、失敗の原因が明らかになっていることが必要です。