SuperAPI AI Directory

recon

Coding & development

View repository

Updated 11-05 16:17

About this skill

recon — Codebase Topology & Architecture Cartography Engine

Domain Rubric

1. Cartography Dimensions

  • Topography & Module Seams: Entrypoints, schemas, data models, and architectural boundaries between subsystems.
  • Key Execution Flows: Sequential call chains tracing runtime dispatch from intake to terminal state persistence with exact code pointers (file:///path/to/file#L<N>).
  • System Invariants & Gotchas: Transaction boundaries, state lifecycles, hidden side-effects, or specification drift.

2. Exploration Guardrails (What to Ignore)

  • Focus strictly on architectural transitions and module seams; forbid cataloging trivial leaf utilities, transient test fixtures, or dumping raw directory listings.

Canonical Output Contract

# 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> (#L) ──
  2. <Symbol> (#L) ── <Intermediate dispatch, orchestration, or validation>
  3. <Symbol> (#L) ── <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>

### Routing

- Caller requests a change whose direction is settled and execution paths/mutation boundaries are clear → (via /changeset).
- Discovered architectural tensions, trade-offs, or multiple viable implementation paths → (via /clarify).

## Execution Protocol

### Phase 1: Macro Anchor Grounding

1. Ingest target subsystem or codebase scope.
2. Scout high-level architectural anchors (entrypoints, key schemas, router boundaries) using file and symbol tools.
3. Establish anchor coordinates before deep inspection.

### Phase 2: Scale-Adaptive Cartography

1. Evaluate target scope scale:
   - *In-Turn Execution* (< 10 files or single cohesive module): Trace call flows against discovered anchors directly in-turn to eliminate subagent latency and token overhead.
   - *Subagent Fan-Out* (broad codebase or cross-layer scopes): Launch concurrent `research` subagents dynamically scaled to partitioned layers or caller-declared budget (Role: `Cartography Scout (<Layer>)`). Seed each with target boundary, discovered anchors, and Canonical Output Contract (offload extensive traces to `.agents/scratch/recon-<layer>-dossier.md`).

### Phase 3: Synthesis & Turn-Halt Gate (Fan-in)

1. Reconcile findings into the Canonical Output Contract with pointers to any offloaded dossiers.
2. Present the completed cartography into the conversation stream and halt turn immediately.