spelunking-specs

Spelunking: turn an unknown app into living specs

A codebase nobody has fully mapped is a liability — every new agent re-derives the same conventions, repeats the same wrong assumptions, and misses the invariants that aren't written down anywhere. Codebase recon is the deep-dive that fixes that: agents ingest the code, infer how it actually works and the standards it follows, verify each claim against real file:line evidence, and write it down as a set of living specs that live in the repo beside the code. Those specs are then refined forward — each pass and each new feature sharpens them, so the team's shared understanding compounds instead of evaporating.

These specs document discovered reality (what the code does, with evidence) and the standard it implies (the convention a new contributor should follow), and they flag drift — where the code violates its own pattern — as open questions rather than silently normalising it. Domains are auto-discovered from the codebase, not seeded from a fixed list.

The spec set: numeric references, git-versioned

Every spec has a numeric dotted reference — domain.subdomain.instance, each segment a number:

• 1 — a top-level domain (e.g. whatever discovery names #1).
• 1.2 — a subdomain within it.
• 1.2.3 — a specific instance/spec (the leaf).

The reference is an address, not a version — git is the version history, so specs carry no version number and are never duplicated per-revision. Each leaf reference is one Markdown file:

<specs-dir>/
  _index.md                       # the registry — number ⇄ domain/title/file/confidence
  1.1.1-session-refresh.spec.md
  1.1.2-session-expiry.spec.md
  1.2.1-oauth-google.spec.md
  2.1.1-user-schema.spec.md
  3.1.1-structured-logging.spec.md

The number is canonical; the -slug is a human convenience (a slug rename is cosmetic, done with git mv). <specs-dir> defaults to specs/ at the repo root (a project may bind it elsewhere).