Your first data page in ten minutes

Vendor the tool

One file, no install, no dependencies. Commit it: the version it was vendored at is recorded in its header, and a repository that carries its own validator can still be checked in five years.

Scaffold a page

One page per dataset, named after its slug. The template is a to-do list: it does not validate until you have filled in who publishes the data, where it comes from, and what the pitfall is.

Fill the manifest, and write the pitfall first

Publisher, source_urls, status — and pitfall: one sentence naming the single thing most likely to trip up somebody who touches this data cold. It is required because it is the line that travels furthest, into the index and into an agent's context, often without the rest of the page.

Add subject too, if the dataset has a landing page. It is the identity claim — what dataset this is, as opposed to where you fetch it — and it is how anyone else's page about the same data can be found alongside yours.

Register the issue you already know about

Title it by the symptom, not the diagnosis: "rate cells are strings", not "inconsistent typing" — that is how the next person searches. Then the four required judgments: what happens if you ignore it (effect), what kind of problem it is (type), whether it is still true (status), and where it applies ([issue.scope]).

If it is a misleads or a context issue, write the misuse: the wrong conclusion a careless-but-reasonable reader would publish. That sentence is usually the most valuable line on the page.

Point the issue at the code, and the code back at the issue

If you have already worked around it, set status = "mitigated" and list the code in handled_by. Then put the anchor comment beside the workaround. One line of why this looks weird next to it is good manners; three lines is a fork of the page.

Now grep -rn "ergo: my-dataset" finds every workaround in the repository, and deleting either half fails the check instead of quietly changing a number.

Record how you checked it

A [validation] block: the date, the method, and the result with numbers in it. "7 of 7 spot figures match within rounding" beats "we checked", because the number is what lets the next check detect drift.

Generate the index

One row per dataset — status, issue counts by effect, core flagged, and the pitfall. Regenerate it on commit; never hand-edit it.

Point your agents at it

Agents do not discover documentation at well-known paths; they go where they are pointed. Two or three lines in CLAUDE.md or AGENTS.md is what makes the rest of this work — the digest and the pages carry the weight.

## Data documentation

Every dataset we ingest has an ergo data page in `docs/data/`, indexed by
`docs/data/INDEX.md`. Read the page before writing code against a dataset:
issues carry stable ids, the ids are anchored in the code that works around
them, and `python3 tools/ergo.py check docs/data --repo .` validates that
contract.

For agents that maintain the pages as well as read them, copy the skill into your skills directory. It covers both roles: consulting the registry before writing code, and registering an issue at the moment of discovery.

Put the check in CI

This is the line that keeps the corpus honest without anyone watching it. --require-manifest closes the directory, so a prose file that quietly stops being a data page is an error rather than a page that silently disappears from the check. Add --strict once you have cleaned the warnings, and warnings fail too.