aif-recon

name	aif-recon
description	Fast, token-efficient codebase reconnaissance. Given a task, a set of changed files, or a question, it finds the relevant files, their dependents/callers, related tests, and any governing spec/PRD/issue — and returns one concise context report. Divides the tree across parallel subagents when available, falls back to a single sequential sweep otherwise. Use before implementing, debugging, or reviewing, or whenever you need to know where something lives. Triggers on: 'find', 'locate', 'where is', 'scout', 'recon', 'map the codebase', 'gather context', 'what touches'.
license	MIT
metadata	{"author":"ainative-build","version":"1.0.0"}
argument-hint	<task | changed-files | question> [--spec]

aif-recon

Reconnaissance for the codebase: turn a target into a concise map of what's relevant. Built to feed other work (implementation, debugging, review) a tight context report instead of a raw file dump.

Principles: wide-then-deep · divide and conquer · report signal, not noise.

Self-contained — built-ins only: git, Glob, Grep, Read, Bash, and (where available) the Task tool for parallel subagents. Read-only; never edits.

What it answers

Given a target — a task description, a set of changed files, or a plain question — produce:

• Relevant files — the modules that implement or own the target area.
• Dependents / callers — what refers to the changed/target symbols (blast radius).
• Related tests — test files that cover the target modules.
• Spec / governing docs — with --spec (or when asked), the PRD / issue / plan that defines the intended behavior.

Workflow

1. Frame the target → search terms, entry dirs, symbols
2. Wide sweep       → Glob/Grep to size the space + gather candidates
3. Divide & conquer → parallel subagents over disjoint dirs (or one sequential sweep)
4. Deep read        → confirm the true owners; trace dependents & tests
5. Report           → one concise context report

1. Frame the target

Parse the target into concrete search terms: symbol/function/type names, file-type globs, likely directories. For a changed-files target, start from git diff --name-only and the changed symbol names. For a question, extract the nouns that name features/modules.

2. Wide sweep

Use a spread of Glob and Grep patterns to (a) estimate scale (how many files/dirs matter) and (b) collect candidate files. Prefer several narrow patterns over one broad one.

3. Divide & conquer — capability branch (load-bearing for portability)

• If parallel subagents are available (Task tool): split the candidate directories into disjoint segments with NO overlap, and spawn one read-only subagent per segment. Give each the exact dirs/ globs to read and the target it's confirming. Each returns a short segment report. Skip the fan-out when the candidate set is small (≤ ~2 segments) — the overhead isn't worth it; sweep inline.
• Otherwise (Codex, Cursor, or any runtime without subagents): do ONE sequential sweep in this session over the candidate set. Same output, just serial.

Each subagent (or the sequential sweep) must:

• read only its assigned scope; stay within it,
• confirm which candidates truly own the target (open them, don't guess from names),
• for changed/target symbols, Grep the repo for callers/importers (dependents),
• note the test files that exercise those modules,
• return a concise segment summary, not raw file contents.

4. Deep read

Merge segment reports. Open the top owners to confirm. Resolve the dependent set (who breaks if this changes) and the covering tests. Drop false candidates.

5. Spec discovery (--spec, or when the caller asks)

Locate the governing spec in this order and report what you find (or "none found"):

1. Issue/PR references in the relevant commit messages (#123, JIRA-45, "closes …").
2. A path the caller named.
3. A scan of docs/, specs/, .scratch/, plans/, PRD*, RFC* for a matching document.

Report format

Keep it tight — this is fuel for the next step, not an essay.

# Recon — <target>

## Relevant files
- `path/to/file` — what it owns, why it's relevant

## Dependents / blast radius
- `path/to/caller` — how it depends on the target

## Tests
- `path/to/test` — what it covers

## Spec / governing docs        (when --spec or asked)
- `path/to/spec` — the requirement it defines   (or: none found)

## Standards docs               (when asked, e.g. by a reviewer)
- `.editorconfig` / `docs/code-standards*` / linter config / `CONTRIBUTING` — the convention it sets   (or: none found)

## Suggested review groups      (large/multi-area targets only)
- group A: `src/api/`, `src/db/` — backend
- group B: `src/components/` — frontend
  (disjoint file-groups a reviewer can fan out over; omit for a small target)

## Notes & unresolved questions
- gaps, ambiguities, things the caller should confirm

References

• references/scouting-patterns.md — Glob/Grep pattern recipes + how to size and split the tree.

Notes

• Timebox parallel subagents (~3 min each); log any non-responder in the report rather than blocking.
• Each subagent has a bounded context window — hand it a scope it can actually read, not the whole tree.