recon

recon — コードベースのトポロジーとアーキテクチャを描き出すエンジン

ドメイン基準

1. カートグラフィーの対象

• トポロジーとモジュール境界：エントリーポイント、スキーマ、データモデル、サブシステム間のアーキテクチャ上の境界。
• 主要な実行フロー：ランタイムのディスパッチから終端状態の永続化までをたどる逐次的な呼び出しチェーン。正確なコード参照（file:///path/to/file#L<N>）を付けます。
• システムの不変条件と注意点：トランザクション境界、状態のライフサイクル、隠れた副作用、仕様の乖離。

2. 探索のガードレール（対象外とするもの）

• アーキテクチャの移行点とモジュール境界に厳密に焦点を絞ります。些細なリーフユーティリティ、一時的なテストフィクスチャの一覧化や、生のディレクトリ一覧の出力は禁止します。

正式な出力仕様

# Codebase Cartography: <Subsystem / Target Scope>

## 1. Topography & Architectural Seams
- **Entrypoints**: <Primary intake points, commands, public APIs, or event consumers with file pointers>
- **Core Contracts & Schemas**: <Key interfaces, data types, state schemas, or governing specifications>
- **Module Boundaries**: <Key directories/packages and their distinct architectural responsibilities>

## 2. Key Execution Flows
### Flow: <Primary Flow Name, e.g., Data Intake / Transformation / Render Pipeline>
1. `<Symbol>` ([<file>#L<N>](file:///path/to/file#L10)) ── <Trigger or input intake>
2. `<Symbol>` ([<file>#L<N>](file:///path/to/file#L50)) ── <Intermediate dispatch, orchestration, or validation>
3. `<Symbol>` ([<file>#L<N>](file:///path/to/file#L90)) ── <Core state transition, persistence, or terminal execution>
*(Add secondary flow if distinct execution path exists)*

## 3. Invariants & Gotchas
- **Invariants (Must Preserve)**: <Core rules, transaction boundaries, or state lifecycles that cannot be broken>
- **Gotchas (Watch Out)**: <Hidden side-effects, spec drift, or surprising couplings; state 'None observed' if clean>

ルーティング

• 変更の方向性が定まり、実行パスと変更境界が明確な変更依頼 → （/changeset 経由）。
• アーキテクチャ上の緊張関係やトレードオフ、実装方法が複数見つかった場合 → （/clarify 経由）。

実行プロトコル

フェーズ 1：主要な足場の把握

1. 対象のサブシステムまたはコードベースの範囲を取り込みます。
2. ファイルおよびシンボルのツールを使って、アーキテクチャの主要な足場（エントリーポイント、主要なスキーマ、ルーターの境界）を調査します。
3. 詳細な調査に入る前に、足場の座標を確定します。

フェーズ 2：規模に応じたカートグラフィー

1. 対象範囲の規模を評価します。
   • ターン内実行（ファイル数が 10 未満、または一貫性のある単一モジュール）：発見した足場に沿って、そのターン内で呼び出しフローを直接追跡し、サブエージェントによる遅延とトークンのオーバーヘッドを排除します。
   • サブエージェントへの分散（広範なコードベース、またはレイヤーをまたぐ対象範囲）：分割したレイヤー、または呼び出し元が指定した予算に応じて動的に調整し、並行するresearchサブエージェントを起動します（役割：Cartography Scout (<Layer>)）。各サブエージェントには、対象範囲の境界、発見した足場、正式な出力仕様を与えます（詳細なトレースは.agents/scratch/recon-<layer>-dossier.mdに委任します）。

フェーズ 3：統合とターン停止ゲート（集約）

1. 調査結果を、外部委任した資料への参照とともに正式な出力仕様にまとめます。
2. 完成したカートグラフィーを会話ストリームに提示し、直ちにターンを終了します。