Spec Mining

Extract a specification from a system that has no usable documentation, by reading the code that actually runs.

The discipline that makes the output trustworthy: separate what you observed from what you inferred. A reader will act on this document — rebuilding a service, planning a migration, onboarding — and a confident-sounding guess is worse than an acknowledged gap, because nobody goes back to check it.

Approach

Work outside-in: entry points, then routes, then the services behind them, then the data layer. Following an actual request path teaches you the system's real structure, which is often not the structure its directory names advertise.

Read the tests too. They document intended behaviour and edge cases someone hit in production, and they are usually more honest than any comment or README in the repo.

Read the migration history as well. Migrations are dated and ordered, so they show how the schema arrived at its current shape — which columns were added under pressure, what was backfilled, what was renamed but never dropped. That sequence is often the only surviving record of why the data model looks the way it does.

Every observation cites its evidence — src/auth/jwt.strategy.ts:42. Without a location the reader can't verify a claim, and unverifiable claims are what make reverse-engineered specs rot.

Writing observed requirements — EARS

EARS keeps requirements unambiguous by forcing the trigger and the state into the sentence, so "the system validates the token" can't hide when.