Decide what every table
in your database is.
Two hundred tables, and nobody can say what half of them are for. Rivering sorts every one into a river or a noun, measures the evidence against your live database, and tells you what is good, what is broken, and what can actually be fixed.
A shop with two answers.
A shop writes every sale in a notebook. Then somebody writes the running total on a whiteboard, which is quicker to read. One day the two disagree, and nobody can tell which one is wrong. Both were written by hand, and both look equally official.
Databases do this all the time. A counter is nudged up from six places and drifts. A "duplicate" log line gets deleted, and it turns out to have been the only copy. Nothing errors and no test fails. The data is just quietly wrong.
Two kinds of table, and the shapes they take.
Ask one question of any table: does a row describe something that happened, or something that is? The answer is its kind. The kind tells you what you may write to it, what you may delete, and what breaks if you get it wrong.
The river
What happened. A verb, in order, never edited.
"Levan paid £240 on Tuesday."
The noun
What is. A thing, current, may be replaced.
A contact, a course, a product.
Six questions, in order.
Run them on a table you have never seen. The first "yes" gives you the answer, with one exception: at question one you keep going. Most tables are settled in one or two steps.
- Does a row describe something that happened?Keep going: a heartbeat is a river too.→ river
- Does one row mean nothing on its own?No, but every row is a fact and there are far too many per subject? That is a branch.→ heartbeat
- Would deleting a row make something happen twice?→ lock
- Can you name the line that would have to be written?If you can, it is derived. If nothing writes that line yet, it is derived with a gap.→ derived
- Has the moment it describes finished?→ summary · state
- Is it a thing in its own right, with its own identity?→ noun
- None of the above: the table is unrivered. Put it on the list.
What it found in one real production database.
270 tables, measured live. Every number comes with the count it is out of.
A counter nobody had classified
Poll answers were kept as a running total, bumped from six places and never recounted. Every filter that asked "did they answer a poll?" had been wrong for months.
The arrow drawn backwards
Log lines were marked for deletion as duplicates of an enrolment table. For most of them, the rows they supposedly duplicated had been deleted years before. The log was the only copy left.
A log filled with heartbeats
An audit log recorded every web request, typing indicators included. The few entries that mattered were deleted after 90 days, on a schedule meant for the noise.
And most of it was already right
A report that is all problems reads as an attack and gets ignored. Rivering says what is working, and it says it first.
Point Claude Code at a database. Get a report you can act on.
The skill runs the whole method from start to finish. It only reads your database and never writes to it. It asks you one question, which database to measure, and then works through to the end on its own.
- Phase 0
Orient
Finds the stack, the schema and the databases it can reach. Then it asks which one to measure. It uses a local copy by default, and production only if you say so.
- Phase 1
Collect evidence
probe.pyreads row counts, fill rates, vocabularies, foreign keys and unique indexes. It works in a read-only transaction and runs nothing butSELECT. - Phase 2
Classify every table
ladder.pyanswers the six questions from the evidence. At most four subagents settle the tables it cannot. - Phase 3
Cross-table checks
Looks for two logs of one thing, locks sitting inside logs, counters with no rebuild, and references nothing enforces.
- Phase 4
Verify itself
Checks every headline number a second way. Before it reports a zero, it runs the same check on a case known to match.
- Phase 5–6
The plan, written down
Writes an HTML report with the fixes in dependency order, each one marked Ready, Blocked, Needs a decision or Not worth it. A register in the repo keeps every decision for the next run.
One command.
1 · Clone it into your Claude Code skills folder
2 · Open Claude Code in your project and run it
Or just ask for it in plain words: "river this database", "which of these tables are logs?", "what is safe to delete?"
Needs
On another database, the skill still classifies every table from the schema, and it says clearly that nothing was measured. To update, run git -C ~/.claude/skills/rivering pull.
No Claude Code? The two tools run on their own: python3 probe.py --dsn postgres://…, then python3 ladder.py probe.json.
Four documents, one method.
They are written to be read by people who don't write code, and they are kept in step with each other and with the skill.
Rivering, Step by Step
The whole idea from nothing, in forty-two short steps. No database words for the first two parts.
Read the booklet →Rivers and Their Direction
Every kind and archetype with its rules, the ladder, the checklists, and one real system worked through start to finish.
Open the reference →What Rivering Proves
Which claims are theorems, which are empirical, and which are only preference. Each one comes with what would prove it wrong.
Check the arguments →The Falsification Record
What we tried to break, what survived 270 real tables, and the defects the testing found. Every one of them was in our own tools.
See what broke →How far this has been tested.
The method was built on one relational database of 270 tables. It was then reasoned against seven outside domains on paper: double-entry accounting, inventory, bitemporal records, time-series, graph databases, warehouse schemas and document stores. None of them needed a third kind. Anything that did not fit became a mark, a rule or a new archetype.
That is a small sample, and we say so. If you run it on a system we have never seen and a table fits neither kind, please open an issue. That is the most useful thing that could happen to it.