The word in your shop that means two things

We did this to ourselves this week, which is the only reason we can describe it precisely. We added a build rule meant to find one word anywhere on our own site. The rule was correct, the word was right, and it stopped the build on six passages across four pages — every one of them copy we had written deliberately, about something else entirely. The word named two things. We had forgotten one of them.

A name is not a key

Every catalogue accumulates these, and they are invisible until something reads the shop mechanically. A finish called Natural and a colour called Natural. A size Small and a product line Small Batch. A material Linen and a collection Linen Season. On screen nobody is confused for a second, because a human reads the surrounding row, the photo and the price. A rule reads the characters.

What makes it specifically dangerous is that the collision is usually between an old thing and a new one. The old name has been in the shop for years and has spread — into product titles, alt text, collection descriptions, filters, ad copy. The new one was added last month by someone who checked that the name was not already taken as a product, which it was not, because it was taken as an attribute. Both are reasonable. Together they are a trap, and the trap is only sprung by whoever next writes a rule.

Run the find without the replace

The cheap habit that catches almost all of it costs a minute. Before any bulk edit, run the find on its own and read every match, not the count. The count is the number that lies: fifty-two matches where you expected fifty tells you nothing about whether the two extras are typos or a different product line. We only caught ours because the rule was wired into a build that refuses to finish, and printed the passages rather than the number.

The second habit is to be suspicious of short names. A one-word name is the one most likely to be already in use somewhere in your own copy as an ordinary word, and the shorter it is the more ways it can turn up inside other words. If you are naming something now, the two-word version costs you nothing and removes the whole class of problem before it starts.

Fix the name, not the rule

When you do find a collision, there are two ways out and only one of them holds.

• Make the rule cleverer. Narrow it with the words that happen to sit around each use today. This works, it takes ten minutes, and it is fragile in a way that is hard to see: the rule is now tuned to copy you have already written. The next person to write a sentence about either thing, in any phrasing you did not anticipate, breaks it — and it breaks silently, because a rule that matches nothing looks exactly like a rule with nothing to find.
• Make the name longer. Change the newer of the two in the data itself, so it is distinct everywhere it appears rather than everywhere you remembered to narrow. This is more work once and no work afterwards. It also fixes the problem for every other rule anyone writes later, including the ones written by people who never heard about this.

We took the first option, and we should say plainly that it was the expedient one rather than the right one. It is written down beside the rule, with the six passages it wrongly caught, so the next person meets the reasoning instead of a mysterious exception. That is the minimum when you choose the fragile fix: leave the evidence, not just the patch.

The shape underneath is one we keep running into from different directions. We have written about how a comparison table stops carrying its column headings once the text loses its boundaries, and about how your later collection pages get thinner than your first. All three are the same kind of problem: the shop is fine to look at, and something about it only becomes visible when you read it the way a machine does — flat, without the layout, without the context you supply for free. None of these are hard to check. They are just easy to never check.