Recon

Scaling strategy (critical for large codebases)

If total source files ≤ 200: Classify every file individually into CRITICAL/HIGH/MEDIUM/CONTEXT-ONLY. This is the standard approach.

If total source files > 200: Do NOT classify individual files. Instead:

1. Classify directories (domains) by risk based on directory names and a quick sample:

   • CRITICAL: directories named auth, security, payment, billing, api, middleware, gateway, session
   • HIGH: models, services, controllers, routes, handlers, db, database, queue, worker
   • MEDIUM: utils, helpers, lib, common, shared, config
   • LOW: ui, components, views, templates, styles, docs, scripts, migrations
   • CONTEXT-ONLY: test, tests, __tests__, spec, fixtures

2. Sample 2-3 files from each CRITICAL directory to confirm the classification and identify the tech stack.

3. Report the domain map instead of a flat file list.

4. The orchestrator will use modes/large-codebase.md to process domains one at a time.

What to map

Trust boundaries (external input entry points)

Search for: HTTP route handlers, API endpoints, GraphQL resolvers, file upload handlers, WebSocket handlers, CLI argument parsers, env var reads used in logic, DB query builders with dynamic input, deserialization of untrusted data.

State transitions (data changes shape or ownership)

DB writes, cache updates, queue publishes, auth state changes, payment state machines, filesystem writes, external API calls that mutate state.

Error boundaries (failure propagation)

Try/catch blocks (especially empty catches), Promise chains without .catch, error middleware, retry logic, cleanup/finally blocks.

Concurrency boundaries (timing-sensitive)

Async operations sharing mutable state, DB transactions, lock/mutex usage, queue consumers, event handlers, cron jobs.

Service boundaries (monorepo detection)

Multiple package.json/requirements.txt/go.mod at different levels, directories named services/, packages/, apps/, multiple distinct entry points. If detected, identify each service unit for partition-aware scanning.

Recent churn (git repos only)

Check git rev-parse --is-inside-work-tree 2>/dev/null. If git repo, run git log --oneline --since="3 months ago" --diff-filter=M --name-only 2>/dev/null to find recently modified files. Flag these as priority targets. Skip entirely if not a git repo.

Test file identification

Files matching *.test.*, *.spec.*, *_test.*, *_spec.*, or inside __tests__/, test/, tests/ directories. Listed separately as CONTEXT-ONLY — Hunters read them for intended behavior but never report bugs in them.

Output format

Write exactly one JSON object matching @schemas/recon.schema.json:

{
  "critical": ["src/api/admin.ts"],
  "high": ["src/services/payment.ts"],
  "medium": ["src/lib/parse.ts"],
  "contextOnly": ["src/api/admin.test.ts"],
  "notes": [
    "Express with session auth and PostgreSQL.",
    "Single-service repository.",
    "Threat model loaded from .bug-hunter/threat-model.md."
  ]
}

Do not append prose after the JSON object.