database-documentation

# database-documentation Document a database so completely and accurately that the docs are **provably** the schema, not a plausible guess at it. A half-correct schema doc is worse than none: people trust it and write broken code. ## The one principle: grounded AND verified Every statement in the output must be: - **grounded** — traceable to a concrete source, preferring the **live database** (introspection of the system catalog). ORM models, migrations, generated types, and seeds are *claims about* the database, not the database; the catalog is what actually runs. - **verified** — confirmed by re-introspecting the live database and diffing it against the generated docs until the diff is empty or every remaining difference is explicitly justified. Never write "documentation is complete" — instead make the diff empty and show it. A frontier model left to itself reads the ORM, writes confident prose, and ships an **incomplete and partly hallucinated** schema (missed check-constraint enums, wrong `ON DELETE`, omitted legacy tables, invented columns). This skill exists to defeat exactly that. Two mechanisms do it: (1) the live DB is the oracle, and (2) judgment is never one agent's call — independent adversaries hunt for what one pass misses. ## Scope (v1): relational/SQL only Targets PostgreSQL, MySQL, SQL Server, SQLite. If you detect a document store (MongoDB) or graph database, **say so and stop on that store** — do not emit relational docs for it (silent mis-do...