123 words for the same thing

A bill moves through a legislature in stages. Introduced, referred to a committee, reported out, passed, signed. Straightforward, until you try to track four legislatures at once and discover that no two of them describe those stages with the same words.

Across four states I counted 123 status labels between them, and only 44 of those were distinct strings. Some were genuinely different stages. Most were the same event wearing different clothes, and a handful looked identical but were not, which is the dangerous category.

The wrong fix is a lookup table

The obvious approach is to map every label to a canonical one and move on. It works until a state changes its wording, or adds a stage, and then your table is quietly wrong and nobody notices for a month.

What I did instead was model the underlying thing: a bill has a position in a sequence, and each state's vocabulary is a translation layer sitting on top. The platform reasons about position. The labels are display. When a state changes its wording, one translation layer changes and nothing else does.

This is not a legislature problem

Every organisation I have built for has a version of this. Two departments use the same word for different stages, or different words for the same stage, and both are convinced theirs is the obvious one. In a travel approval system, "approved" meant approved-by-supervisor in one office and approved-for-payment in another. Those are weeks apart.

If you build the system around the words people happen to use, you build their disagreement into the database. Then every report is subtly wrong and nobody can explain why the numbers do not match.

What I do about it now

Early in a project I ask people to describe the same process separately, and I write down the words they use. Where two people use one word differently, that is not a naming problem, it is a process that has never been agreed. Finding it in week one is cheap. Finding it after go-live is not.

Then the system stores the stage and shows each group the label they expect. Everyone keeps their vocabulary. The data underneath means one thing.

It also makes the thing survivable. Legislatures change their publishing formats without notice, so the parsers were built to be replaced one state at a time without taking the platform down. The same principle applies to any integration you do not control: assume it will change, and make sure that change is contained.