<b>The entity disambiguation SOP</b>

<b>The entity disambiguation SOP</b>

At scale you will have two entities that look identical to your slug generator: two towns named Springfield, two products with the same model name. Disambiguate at the data layer, not the render layer.

Step 1 — Owner: data lead. Define the natural key: the combination of fields that makes an entity unique (name + region + type). Gate: natural key produces zero collisions across the dataset.

Step 2 — When the natural key still collides, append a stable qualifier to the slug (springfield-il vs springfield-ma). Gate: qualifier comes from a field, never a counter (-2, -3 is forbidden).

Step 3 — Owner: dev. Persist the resolved slug. A later data refresh must reuse it, not regenerate.

Step 4 — Add the qualifier to the H1 and title too, so the page reads unambiguously to users and search engines.

— Numeric suffix slugs (-2, -3) are a tell of a broken key; they shuffle on every rebuild
— Disambiguate with meaning, not with counters

Ship gate: don't publish until the natural key returns zero unqualified collisions.