scout

高速で軽量なコードベーススキャン。Scoutは Rune エコシステムの目です。

Instructions

呼び出されたときは、以下のステップを実行してください：

Phase 1: 構造スキャン

プロジェクトレイアウトをマッピングします：

1. Glob で **/* を使用してディレクトリ構造を理解する
2. Bash を使用してキーディレクトリ（root、src、lib、app）で ls を実行
3. これらのファイルを検出してフレームワークを特定：
   • package.json → Node.js/TypeScript
   • Cargo.toml → Rust
   • pyproject.toml / setup.py → Python
   • go.mod → Go
   • pom.xml / build.gradle → Java

TodoWrite: [
  { content: "Scan project structure", status: "in_progress" },
  { content: "Run targeted file search", status: "pending" },
  { content: "Map dependencies", status: "pending" },
  { content: "Detect conventions", status: "pending" },
  { content: "Generate codebase map (if full scan)", status: "pending" },
  { content: "Generate scout report", status: "pending" }
]

Phase 2: ターゲット検索（検索優先）

検索優先の原則：新しいものを構築する前に、scout は既存のソリューションがコードベース内、パッケージレジストリ、または利用可能な MCP サーバーに存在するかどうかを確認します。

採用 / 拡張 / 構成 / 構築の意思決定マトリックス：

Scout が呼び出し元のターゲットドメインを見つけたときは、以下のように分類します：

ADOPT     — 完全一致が存在（コードベース、npm、PyPI、MCP 内）。そのまま使用。
EXTEND    — 部分一致が存在。既存ソリューションを拡張/設定。
COMPOSE   — 複数のパーツが存在。それらを一緒に接続。
BUILD     — 適切なものが存在しない。ゼロから構築。

分類を呼び出し元スキルに報告してください。これは cook の Phase 2（PLAN）に通知します。ADOPT と EXTEND は BUILD よりはるかに安価です。

深いスキャンの前のクイックチェック：

1. 対象機能の既存実装についてコードベースを Grep で検索
2. インストール済みパッケージについて package.json / pyproject.toml / Cargo.toml を確認
3. タスクが外部データ/API を含む場合：役に立つ可能性のある利用可能な MCP サーバーを記録

スキャンリクエストに基づいて、焦点を絞った検索を実行します：

1. Glob を使用してターゲットドメインに一致するファイルを検索：
   • Auth ドメイン：**/*auth*、**/*login*、**/*session*
   • API ドメイン：**/*.controller.*、**/*.route.*、**/*.handler.*
   • Data ドメイン：**/*.model.*、**/*.schema.*、**/*.entity.*
2. Grep を使用して特定のパターンを検索：
   • 関数名：pattern: "function <name>" または "def <name>"
   • クラス定義：pattern: "class <Name>"
   • インポートステートメント：pattern: "import.*<module>" または "from <module>"
3. Read を使用して最も関連性の高いファイルを確認（最大 10 ファイル、関連性でソート）

検証ゲート：少なくとも 1 つの関連ファイルが見つかった、または対象が存在しないことを確認します。

情報飽和度検出（いつやめるかを知る）

Scout のデフォルトは「最大 10 ファイル読み込み」ですが、本当の問題は追加の読み込みが生産性があるかどうかです。Phase 2 スキャン全体の飽和度を追跡します：

エンティティ追跡：ファイルをスキャンするときに、主要エンティティ（関数名、クラス名、インポート、API エンドポイント、設定キー）を抽出します。検出されたエンティティのランニングセットを保持します。

シグナル	しきい値	意味	アクション
新規エンティティ比率	最後の 2 ファイル読み込みで新規エンティティが 2 未満	このドメインの検索は完了	スキャンを停止し、Phase 3 に移動
コンテンツ類似度	最後の 2 ファイルが同じインポート/パターンの 70% 以上を共有	ファイルが同じモジュール内、冗長な読み込み	このディレクトリの残りのファイルをスキップ
クエリバリエーション	異なるパターンの 3+ の Glob/Grep クエリがすべて同じファイルを返す	すべての検索角度が収束	ドメインは完全にマップされ、進みます

飽和度が検出されたとき：Scout Report で発行：

### 飽和度
- [N] ファイル読み込み後に到達 — 最後の 2 読み込みで [M] 個の新規エンティティを追加
- 推奨事項：synthesize_and_report（さらなるスキャンは新しい情報をもたらす可能性が低い）

なぜか：飽和度検出がないと、scout は 3 つのファイルに既に必要なすべてが含まれている場合でも、フルバジェットの 10 ファイルを読み込みます。これはコンテキストトークンを浪費し、呼び出し元スキルを遅延させます。早期の飽和度検出により、制御がより速く返されます。

Phase 3: 依存関係マッピング

1. Grep を使用して識別されたファイル内の import/require/use ステートメントを検索
2. どのモジュールがどのモジュールに依存するかをマップ（A → imports → B）
3. 潜在的な変更の影響範囲を特定：ターゲットファイルをインポートするファイル

Phase 4: 慣例検出

1. Glob を使用して設定ファイルを確認：
   • .eslintrc*、eslint.config.* → ESLint ルール
   • tsconfig.json → TypeScript 設定
   • .prettierrc* → Prettier 設定
   • ruff.toml、.ruff.toml → Python リンター
2. 2-3 個の代表的なソースファイルを読んで命名規則を確認
3. Glob で既存テストを検索：**/*.test.*、**/*.spec.*、**/test_*
4. テストフレームワークを確認：jest.config.*、vitest.config.*、pytest.ini

Phase 4.5: ズームアウトモード

呼び出し元から mode="zoom-out" で起動、または agent.stuck シグナルでリスン時に自動起動（fix が同じファイルで 2 回以上失敗した後、または debug が 3 回以上反証仮説サイクル後に発行）。

アクティベートされた場合、scout は 3 層上昇マップを生成します：

レイヤー	含まれるもの	キャップ
L0（ターゲット）	スタックファイルのシンボル+直接的なインポート	無制限
L1（兄弟）	同じディレクトリのファイル+パブリックエクスポート	8 ファイル
L2（呼び出し元/隣接）	L0 のエクスポートをインポートするモジュール+同じドメインの隣接モジュール	8 モジュール

出力は Mermaid ダイアグラムで、単なるファイルリストではなく、エージェントがスタックした場合のビジュアルは付加価値です。

graph LR
  target[src/auth/login.ts]:::stuck
  target --> dep1[crypto.compare]
  target --> dep2[db.users.get]
  caller1[src/routes/auth.ts] --> target
  caller2[src/middleware/protect.ts] --> target
  sibling1[src/auth/refresh.ts] -.same-dir.- target
  sibling2[src/auth/logout.ts] -.same-dir.- target
  classDef stuck fill:#ff6b6b

境界 — L2 上昇は 8 モジュールで上限です。超過した場合は「インポート頻度でトップ 8 を表示」に折りたたみます。上限を静かに超えないでください。

マップを発行した後、scout は通常の Phase 6（レポート生成）に戻り、ズームアウトセクションをプライマリ出力として使用します。

Phase 5: コードベースマップ（オプション）

cook、team、onboard、autopsy（フルプロジェクト理解が必要なスキル）によって呼び出されるとき、構造化されたコードベースマップを生成します：

1. 以下を含む .rune/codebase-map.md を作成：

## コードベースマップ
生成：[タイムスタンプ]

### モジュール境界
| モジュール | ディレクトリ | パブリック API | 依存関係 | ドメイン |
|---------|-----------|-----------|--------|--------|
| auth | src/auth/ | login()、logout()、verify() | database、config | 認証 |
| api | src/api/ | routes、middleware | auth、database | HTTP レイヤー |

### 依存関係グラフ（Mermaid）
​```mermaid
graph LR
  api --> auth
  api --> database
  auth --> database
  auth --> config
​```

### ドメイン所有権
| ドメイン | モジュール | キーファイル |
|--------|----------|-----------|
| 認証 | auth、session | src/auth/login.ts、src/auth/verify.ts |
| データレイヤー | database、models | src/db/schema.ts、src/models/ |

2. ディレクトリ構造から（トップレベルの src/ サブディレクトリ、または検出されたフレームワーク慣例）モジュールを導出
3. パブリック API = 各モジュールのインデックス/エントリファイルからエクスポートされた関数/クラス
4. 依存関係 = モジュール間のインポートステートメント（Phase 3）
5. ドメイン = モジュール名+ファイル内容から推論（auth、payments、frontend、infra、data、config など）

このフェーズをスキップ：ターゲット検索のみが必要なスキル（debug、fix、review、sentinel）によって呼び出されるとき。

Phase 6: レポート生成

呼び出し元スキル用に構造化された出力を生成します。TodoWrite を完了に更新します。

制約

• 読み取り専用：Edit、Write、または破壊的なコマンドを使用した Bash を使用しない。例外：Phase 5 は cook、team、onboard、autopsy によって呼び出されたときに .rune/codebase-map.md を書き込むことができます
• 高速：スキャンごとに最大 10 ファイル読み込み。関連性スコアでソート
• 焦点を絞った：リクエストに関連したもののみをスキャン、コード全体ではない
• 副作用なし：キャッシュ、保存、変更をしない

エラーリカバリー

• Glob が 0 結果を返す場合：より広いパターンを試して、「見つかりません」と報告
• ファイルの Read が失敗した場合：スキップして、レポートに記録して、残りのファイルで続行
• プロジェクトタイプが曖昧な場合：複数の設定ファイルを確認、曖昧な場合はすべての候補を報告

呼び出し（送信）

なし — Glob、Grep、Read、Bash ツールを直接使用する純スキャナー。他のスキルを呼び出しません。

呼び出し元（受信）

• plan（L2）：計画の前にコードベースをスキャン
• debug（L2）：根本原因分析のために関連コードを検索
• review（L2）：レビュー中のコンテキストのために関連コードを検索
• fix（L2）：コード変更前に依存関係を理解
• cook（L1）：Phase 1 UNDERSTAND — コードベースをスキャン
• team（L1）：フルプロジェクト範囲を理解
• sentinel（L2）：変更されたファイルをセキュリティ問題でスキャン
• preflight（L2）：影響されたコードパスを検索
• onboard（L2）：CLAUDE.md 生成のためのフルプロジェクトスキャン
• autopsy（L2）：包括的なヘルスアセスメント
• surgeon（L2）：リファクタリング前にモジュールをスキャン
• marketing（L2）：機能説明のためにコードベースをスキャン
• safeguard（L2）：セーフティネット追加前にモジュール境界をスキャン
• audit（L2）：Phase 0 プロジェクト構造とスタック発見
• db（L2）：スキーマとマイグレーションファイルを検索
• design（L2）：UI コンポーネントライブラリと設計トークンをスキャン
• perf（L2）：ホットパスファイルとパフォーマンスクリティカルコードを検索
• review-intake（L2）：レビューコンテキストのためにコードベースをスキャン
• skill-forge（L2）：新しいスキル作成時に既存スキルをパターンでスキャン
• ba（L2）：要件抽出前にコンテキスト用の既存コードベースをスキャン
• retro（L2）：回顧分析のためにコミット履歴とコードベースをスキャン
• graft（L2）：外部リポジトリからコードを移植する前にターゲットコードベースをスキャン
• docs（L2）：ドキュメント生成のためにコードベース構造をスキャン
• logic-guardian（L2）：保護マッピング用にビジネスロジックモジュールをスキャン
• adversary（L2）：レッドチーム分析の前にコードベースをスキャン
• improve-architecture（L2）：入力コンテキストが古い場合にターゲットモジュール+呼び出し元を再スキャン

出力形式

## Scout Report
- **Project**: [name] | **Framework**: [detected] | **Language**: [detected]
- **Files**: [count] | **Test Framework**: [detected]

### 関連ファイル
| ファイル | 関連理由 | LOC |
|---------|---------|-----|
| `path/to/file` | [理由] | [行数] |

### 依存関係
- `module-a` → imports → `module-b`

### 慣例
- 命名：[検出されたパターン]
- ファイル構造：[パターン]
- テストパターン：[パターン]

### 検索優先評価
- **分類**：ADOPT | EXTEND | COMPOSE | BUILD
- **既存ソリューション**：[見つかった場合、何が見つかったか]
- **推奨事項**：[簡潔な根拠]

### 観察
- [パターンまたは注目される潜在的問題]

返却内容

アーティファクト	形式	場所
Scout Report	Markdown（インライン）	呼び出し元スキルに発行
コードベースマップ	Markdown	.rune/codebase-map.md（cook、team、onboard、autopsy によって呼び出されるとき）

Sharp Edges

このスキルの既知の障害モード。完了と宣言する前にこれらを確認してください。

障害モード	重大度	軽減策
すべてのファイルではなくターゲット検索を読み込み（50+ ファイルスキャン）	中程度	最大 10 ファイル読み込みを強制 — 呼び出し元のドメインに関連性でソート
より広いパターンを試さずに「見つかりません」を報告	中程度	より広い glob を最初に試す（例：**/*auth* → **/auth* → **/*login*）、その後見つかりません
不正なフレームワーク検出がすべてのダウンストリーム計画に影響	高	複数の設定ファイルを確認；曖昧な場合はすべての候補を報告し、推測しない
Phase 3 での依存関係の影響範囲の漏れ	中程度	Phase 3 は必須 — 呼び出し元はターゲットをインポートする他のものを知る必要があります

完了条件

• プロジェクト構造をマップ（ディレクトリレイアウト、エントリポイント）
• フレームワークを設定ファイルから検出（または「曖昧」と候補をリストアップ）
• 呼び出し元のドメイン用ターゲット検索を完了
• ターゲットファイルの依存関係影響範囲を特定
• 慣例を検出（命名、テストフレームワーク、リントファイル設定）
• コードベースマップを .rune/codebase-map.md に書き込み（cook、team、onboard、autopsy によって呼び出されるとき）
• Scout Report を構造化形式の関連ファイルテーブル付きで発行

コストプロファイル

~500-2000 トークン入力、~200-500 トークン出力。常に haiku。メッシュ内で最も安いスキル。

スコープ保護策：親エージェントによって明示的に委譲されない限り、スキャンを関連のないモジュールに拡張したり、.rune/codebase-map.md 以外のファイルに書き込まないでください。