codebase-recon

# Codebase Recon

Build a reusable, falsifiable model of a repository. This skill reports what
the tree and executable probes support; it does not edit code or issue a final
PASS/WARN/FAIL verdict.

## Constraints

- To prevent a floating recon, record the exact repository commit and local
  source-of-truth precedence.
- Because confidence is not evidence, type every material claim and cite each
  fact and inference.
- To preserve traceability, prefer a verified delta when a prior pack exists
  instead of rewriting unchanged evidence as fresh discovery.

## Modes, views, and lenses

One skill replaces a cluster of loose recon skills. Steer it with mode, view
emphasis, lens, and depth — do not invent a second skill for each shape.

| Control | Values | Use when |
|---|---|---|
| **Mode** | `baseline` \| `delta` | First pack vs refresh after a prior recon |
| **View emphasis** | mental model · bounded audit · pattern evidence · synthesis | Archaeology-style map, audit-style findings, pattern harvest, or executive synthesis |
| **Lens** | persistence · auth · CLI · build · test (one per pass) | Domain-deep cut instead of a shallow whole-tree sweep |
| **Depth** | quick · standard · deep | Orientation vs onboarding vs decision-grade evidence |

Ask for the shape explicitly, for example:

```text
codebase-recon --mode=delta --view=audit --lens=cli --depth=standard
codebase-recon baseline, mental-model view, persistence lens, deep
```

Natural-language equivalents count. The durable pack still carries all four
views; emphasis changes what you spend tokens on and what the companion report
leads with. Pattern packaging beyond evidence pointers belongs in
[`pattern-mining`](../pattern-mining/SKILL.md). Binding PASS/FAIL stays with
[`validate`](../validate/SKILL.md).

## Workflow

1. Record the current commit and the repository's local source-of-truth
   precedence. Search for validated prior manifests before starting with
   `skills/codebase-recon/scripts/validate-output.sh --repo-root <target> --discover-priors`.
   Successful empty output means no prior pack exists at either documented
   default.
2. If no prior pack exists, use `baseline` mode. If one exists, verify its
   still-valid claims against the current commit and use `delta` mode. Preserve
   valid evidence by reference and describe only changed paths and synthesis.
3. Trace representative paths from entry point to domain logic, integration
   boundary, and test. Prefer a few complete flows over a broad file inventory.
4. Keep four views distinct in the report: mental model, bounded audit, pattern
   evidence, and synthesis. Label each claim `fact`, `inference`, or `unknown`,
   assign confidence, and cite evidence for facts and inferences.
5. List inspected and uninspected scope. Write the JSON manifest and companion
   report, then run the validator. Missing evidence and hidden coverage gaps are
   contract failures, not prose caveats.

## Docs-first entry-point tracing

Enter through what the repository declares about itself — README, architecture
docs, build manifests, CLI help — and only then verify those declarations
against the tree. Before the first broad search, list the declared entry points
and trace at least one of them to code. The named failure mode is grep-first
drift: opening with keyword sweeps builds a model of whatever happened to
match, and the recon inherits the search terms' blind spots instead of the
repository's actual shape. When declaration and code disagree, that is a
finding, not noise: record the doc's claim as `inference`, the traced behavior
as `fact`, and cite both.

## One-domain-deep lens per pass

Each pass adopts exactly one lens — persistence, auth, CLI surface, build
system, test harness — and follows it from entry point through domain logic to
its tests before switching lenses. A pass ends in exactly one of two states:
the lens has one complete entry-to-test flow, or the report names the file and
line where the trace was cut and why. The named failure mode is the shallow
sweep: touching every directory at depth one produces a file inventory that
reads like a model but supports no claim, because no path was followed far
enough to falsify anything.

## Citation floor: file:line or downgrade

The durable output doc earns its keep only if a future reader can re-verify a
claim without redoing the recon. Every `fact` cites file:line; every
`inference` cites the file:line facts it rests on. A claim that cannot be
cited is downgraded to `unknown` before the report ships — never shipped
uncited at its original confidence. The manifest validator checks citations
against the exact Git commit declared by that manifest. They must be safe
repository-relative regular-file paths; artifact-local and external paths are
rejected because this schema has no digest field for those bytes. A supplied
line number must exist in the committed blob. The validator also resolves each
representative flow path at that commit. It does not require every citation to
carry a line number; hold the companion report to the stricter floor: a path
without a line is a pointer to homework, not a citation, and counts as a
coverage gap in the report's own terms.

When reconstructing a repository other than the one that ships this skill, pass
`--repo-root <target>` to the validator so evidence resolves against the target
tree rather than the skill's own checkout.

## Output Specification

- **Artifact directory:** the caller-selected output path, defaulting to `.agents/scratch/codebase-recon/<run-id>/`
- **Filename convention:** `codebase-recon.json` with companion report
  `codebase-recon.md` in the same directory.
- **Format:** `codebase-recon.v1` JSON manifest plus an evidence-cited Markdown
  report covering the same commit, mode, flows, claims, and scope boundaries.
  The manifest's `report` object names `codebase-recon.md` and binds its
  lowercase SHA-256. The report carries one
  `<!-- codebase-recon-report.v1 -->` marker plus `manif