Hai SSOT
For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.
Overview
Hunt down places where one fact, one shape, or one word has more than one authoritative home —
or where one name secretly serves several facts. Produce a findings report that an engineer can
execute from: every finding numbered, evidenced, honestly adjudicated, and routed to a concrete
disposition. The skill is a diagnostic with a strong opinion about treatment, not a linter.
The Core Law
SSOT violations are especially likely at boundaries a single type system cannot protect:
language↔database, language↔wire, typed↔untyped payloads, code↔docs, and production↔fixtures.
They also occur inside one language when modules independently redeclare constants, shapes,
defaults, or derivations; compilers do not prevent semantically duplicated authorities.
Two corollaries that direct the hunt:
- Start at the cross-stack seams because risk is high there, then follow each concept through its
intra-language definitions and consumers.
- A test that pins two copies equal ("parity test", "pin test", "currency test") is a flag:
either the copy should not exist (eliminate it, then delete the test), or both sides are
genuinely real artifacts that cannot share a source (then the test IS the correct treatment).
Locate every such test early — each one marks either a violation or a treatment already applied.
The Ten Symptom Classes
Use the symptom table to choose likely classes, then read only those class recipes in
references/detection-cookbook.md before searching.
| # |
Symptom |
One-line definition |
Canonical tell |
| 1 |
Multi-source literals |
One wire string / enum value defined independently in N places |
Same quoted literal in two modules; a private const shadowing a public one |
| 2 |
Shape proliferation |
One concept carried by N type/schema shapes across seams |
Hand-written schema on one side of a wire mirroring the producing type on the other; typed→untyped "regressions" where a typed object gets flattened back into a string-keyed map at a seam |
| 3 |
Word overload |
One word meaning N different things (the mirror of #1) |
The domain's most valuable word (e.g. "memory" as product moat) also used for infrastructure ("in-memory"); a term with 2-3 documented senses |
| 4 |
Legacy-vocabulary mapping layers |
Old vocabulary survives inside display/fixture mapping functions after a wire rename — and the mappings themselves get copy-pasted |
The same old→new word map appearing in two files; fixtures asserting retired vocabulary |
| 5 |
Dual-pathway behavior forks |
The same operation behaves differently depending on which entry path/host ran it |
A CLI path skipping the safety pipeline the server path runs; one caller passing explicit-empty where another gets defaults |
| 6 |
Scattered defaults |
The same fallback value born independently at multiple layers |
A default directory/timeout/limit defined as a constant in one layer AND as an inline fallback in another, neither referencing the other |
| 7 |
Pure-subset shape pairs |
Type B = type A minus k fields, plus a field-by-field copy converter |
A converter function that only copies fields; the "information" carried by the second shape is merely hiding fields |
| 8 |
Same-name-different-shape |
Two exported types with the same name in the same semantic domain but different fields |
RunSnapshot in two sibling modules meaning related-but-different things |
| 9 |
Redundant conversion chains |
One concept reshaped at multiple hops along a single call path, where the intermediate shapes add no information |
A value converted A→B→C on its way through layers; round-trips (A→B→A); typed→string→typed relays where a value is serialized and re-parsed inside one process. Kill question per hop: "what information does this shape add?" — no answer means the hop merges |
| 10 |
Re-implemented derivations |
The same rule — validation, normalization, parsing, a derived field — implemented independently at N layers, each a drift point |
The same regex/threshold/branching duplicated with small diffs; a date string parsed at three layers; isActive/displayName computed differently in two views |
Severity logic: a violation that has already caused a production symptom (silent empty
rendering, correctness bug, wrong cursor) outranks everything; next, violations on persisted or
user-visible wire; then cross-team/cross-stack seams; intra-module duplication last.
Honest Adjudication — what NOT to flag
Findings are leads, not verdicts. Run these checks before a finding enters the report; record
exonerated candidates in a "not counted" note so the next sweeper doesn't re-litigate:
- Module-qualified generic names are idiomatic, not violations. A short generic type name
qualified by its module (
stream.Message vs processor.Message) is the standard-library
pattern in every module system (see the cookbook's language notes for per-language exemplars).
Flag same-name types only when they share a semantic domain and confuse a cross-module reader
(class #8), or collide in one file.
- Forward contracts are alive even with zero producers. A registry entry / enum value with no
backend producer may be consumed by a frontend switch as a forward contract. Grep every consumer
surface (web, contract, seeds) before calling anything dead. Disposition for these: annotate and
group, never delete on producer-absence alone.
- Persisted wire literals are frozen. The fix unifies definition sites; the string values
on disk/in events never change. Even naming inconsistencies baked into the wire (mixed prefixes)
get documented, not repaired.
- A shape change is legitimate when it carries information — adds a sequence number, hides
internal fields for an audience, renames into a consumer's vocabulary. The disease is reshaping
that carries nothing (class #7), typed→map regressions, and chains where every hop re-converts
without adding anything (class #9). Judge each hop separately: a chain can contain one real
boundary and two gratuitous ones.
- Re-checks at trust boundaries are defense, not duplication. A server re-validating client
input, or a DB constraint backing an app-level check, is deliberate redundancy across trust
levels. Class #10 flags re-implemented rules at the same trust level — two layers behind the
same boundary each owning their own copy of the regex, threshold, or parse.
- Port/impl module pairs and per-plugin modules are conventions, not fragmentation. Don't
recommend flattening them in an SSOT report.
- Deliberate, adjudicated dual vocabularies can exist (e.g. an ADR chose a flat result type
with a closed discriminator). Check decision records before flagging; contrast honestly — a
4-field type with a closed-set kind is not the same disease as a 9-field union with no
discriminator semantics.
The credibility of the whole report rests on this section. One overreaching finding ("unify all
the Messages!") teaches the reader to ignore the real ones.
Treatment Recipes
Every confirmed finding routes to exactly one recipe; the recipe determines the disposition:
| Recipe |
When |
Notes |
| Codegen |
One side can mechanically generate the other (type → schema, registry → enum file) |
Strongest fix; pairs with a currency test (guards "forgot to regenerate" — that is a constructive gap a compiler can't close, so the test is legitimate) |
| Parity guard |
Both sides are real artifacts that cannot share a source (language enum vs DB CHECK constraint) |
Include a red drill: deliberately desync once and confirm the guard fires |
| Constant promotion |
Bare string keys in map envelopes crossing layers |
Promote to a named constant next to its siblings; both writer and reader reference it |
| Typed payload |
Shape proliferation / map regressions at seams |
Often a phase of a larger contract plan; don't band-aid per-field |
| Convert at the edge |
Redundant conversion chains |
Convert once where the value enters the system; pass one canonical type through the interior; merge hops that add no information |
| Single rule owner |
Re-implemented derivations |
Hoist the rule into one named function/type and make every layer call it; where possible encode the proof in the type (parse, don't validate) so downstream layers cannot re-do the work |
| Vocabulary close-out |
Word overload, legacy mapping layers |
Glossary entry + rename of the cheap side; map function single-sourced or fixtures moved to current vocabulary |
| Adjudication |
Behavior forks |
These need a decision, not a patch: unify the behavior, or promote the fork into an explicitly documented contract. Present both options with a default recommendation |
| Delete the pin |
After any recipe eliminates a copy, delete the parity test that was holding the copies together — its survival is evidence of remaining multi-source |
|
Workflow
- Scope. Agree on the sweep surface (a module, a contract plane, the whole repo). Note any
prior sweeps/plans to avoid re-finding adjudicated items.
- Map the seams first. List type-system-unreachable boundaries, then the internal modules that
independently define or derive the same concepts. Seams are priority entrypoints, not the only
possible location of findings.
- Hunt per symptom class using the cookbook greps. For each candidate, capture file:line for
every definition/use site — counts matter ("this literal is defined in exactly 2 places",
"adding one event touches 6 files" is the change-amplification number that lands the point).
- Verify producer AND consumer for anything you might call dead or removable. The
three-surface discipline: backend producers, frontend/contract consumers, seeds/fixtures.
- Adjudicate honestly (section above). Sort exonerated candidates into the "not counted" note.
- Write the report using
references/output-template.md: numbered findings, evidence,
severity, recipe, disposition table, positive list ("already-healthy patterns to copy" —
naming what the repo already does right makes the report constructive and gives fixes a local
precedent to imitate).
- Execute quick wins if asked — constant promotions and literal de-duplications are usually
safe same-day (zero wire change, full test gate). Bigger recipes get routed to plans; behavior
forks get routed to the user as decisions.
Hand off when
- The finding's root cause is a module-boundary or layering problem → hai-architecture.
- A finding needs a new name, or the report turns into a rename list → hai-naming.
- The dispositions need to become a phased, verifiable plan → hai-goal.
- The user wants to reframe the whole contract surface rather than patch findings → geju.
What this skill is NOT
- Not a linter: it reports adjudicated findings with treatment routes, not raw matches.
- Not "unify everything": its credibility comes from the not-counted list as much as the findings.
- Not a wire-migration tool: persisted values are out of bounds; only definition sites move.
1---2name: hai-ssot3description: Diagnoses single-source-of-truth violations—duplicated literals or rules, shape drift, scattered defaults, redundant conversion chains, overloaded vocabulary, and behavior forks—with file:line evidence, false-positive adjudication, and a treatment recipe. Use when the user suspects definitions may diverge, adding one concept requires edits in many places, layers repeatedly convert or validate the same value, or asks about SSOT/双源/漂移/同名异形. Use hai-architecture when the root decision is module ownership rather than duplicated authority.4---56# Hai SSOT78For Chinese readers, see `SKILL.zh_CN.md`. The English `SKILL.md` is the execution source of truth.910## Overview1112Hunt down places where one fact, one shape, or one word has more than one authoritative home —13or where one name secretly serves several facts. Produce a findings report that an engineer can14execute from: every finding numbered, evidenced, honestly adjudicated, and routed to a concrete15disposition. The skill is a diagnostic with a strong opinion about treatment, not a linter.1617## The Core Law1819SSOT violations are especially likely at boundaries a single type system cannot protect:20language↔database, language↔wire, typed↔untyped payloads, code↔docs, and production↔fixtures.21They also occur inside one language when modules independently redeclare constants, shapes,22defaults, or derivations; compilers do not prevent semantically duplicated authorities.2324Two corollaries that direct the hunt:25261. Start at the cross-stack seams because risk is high there, then follow each concept through its27 intra-language definitions and consumers.282. A test that pins two copies equal ("parity test", "pin test", "currency test") is a flag:29 either the copy should not exist (eliminate it, then delete the test), or both sides are30 genuinely real artifacts that cannot share a source (then the test IS the correct treatment).31 Locate every such test early — each one marks either a violation or a treatment already applied.3233## The Ten Symptom Classes3435Use the symptom table to choose likely classes, then read only those class recipes in36`references/detection-cookbook.md` before searching.3738| # | Symptom | One-line definition | Canonical tell |39|---|---|---|---|40| 1 | **Multi-source literals** | One wire string / enum value defined independently in N places | Same quoted literal in two modules; a private const shadowing a public one |41| 2 | **Shape proliferation** | One concept carried by N type/schema shapes across seams | Hand-written schema on one side of a wire mirroring the producing type on the other; typed→untyped "regressions" where a typed object gets flattened back into a string-keyed map at a seam |42| 3 | **Word overload** | One word meaning N different things (the mirror of #1) | The domain's most valuable word (e.g. "memory" as product moat) also used for infrastructure ("in-memory"); a term with 2-3 documented senses |43| 4 | **Legacy-vocabulary mapping layers** | Old vocabulary survives inside display/fixture mapping functions after a wire rename — and the mappings themselves get copy-pasted | The same old→new word map appearing in two files; fixtures asserting retired vocabulary |44| 5 | **Dual-pathway behavior forks** | The same operation behaves differently depending on which entry path/host ran it | A CLI path skipping the safety pipeline the server path runs; one caller passing explicit-empty where another gets defaults |45| 6 | **Scattered defaults** | The same fallback value born independently at multiple layers | A default directory/timeout/limit defined as a constant in one layer AND as an inline fallback in another, neither referencing the other |46| 7 | **Pure-subset shape pairs** | Type B = type A minus k fields, plus a field-by-field copy converter | A converter function that only copies fields; the "information" carried by the second shape is merely hiding fields |47| 8 | **Same-name-different-shape** | Two exported types with the same name in the same semantic domain but different fields | `RunSnapshot` in two sibling modules meaning related-but-different things |48| 9 | **Redundant conversion chains** | One concept reshaped at multiple hops along a single call path, where the intermediate shapes add no information | A value converted A→B→C on its way through layers; round-trips (A→B→A); typed→string→typed relays where a value is serialized and re-parsed inside one process. Kill question per hop: "what information does this shape add?" — no answer means the hop merges |49| 10 | **Re-implemented derivations** | The same rule — validation, normalization, parsing, a derived field — implemented independently at N layers, each a drift point | The same regex/threshold/branching duplicated with small diffs; a date string parsed at three layers; `isActive`/`displayName` computed differently in two views |5051Severity logic: a violation that has **already caused a production symptom** (silent empty52rendering, correctness bug, wrong cursor) outranks everything; next, violations on persisted or53user-visible wire; then cross-team/cross-stack seams; intra-module duplication last.5455## Honest Adjudication — what NOT to flag5657Findings are leads, not verdicts. Run these checks before a finding enters the report; record58exonerated candidates in a "not counted" note so the next sweeper doesn't re-litigate:5960- **Module-qualified generic names are idiomatic, not violations.** A short generic type name61 qualified by its module (`stream.Message` vs `processor.Message`) is the standard-library62 pattern in every module system (see the cookbook's language notes for per-language exemplars).63 Flag same-name types only when they share a semantic domain and confuse a cross-module reader64 (class #8), or collide in one file.65- **Forward contracts are alive even with zero producers.** A registry entry / enum value with no66 backend producer may be consumed by a frontend switch as a forward contract. Grep every consumer67 surface (web, contract, seeds) before calling anything dead. Disposition for these: annotate and68 group, never delete on producer-absence alone.69- **Persisted wire literals are frozen.** The fix unifies *definition sites*; the string values70 on disk/in events never change. Even naming inconsistencies baked into the wire (mixed prefixes)71 get documented, not repaired.72- **A shape change is legitimate when it carries information** — adds a sequence number, hides73 internal fields for an audience, renames into a consumer's vocabulary. The disease is reshaping74 that carries nothing (class #7), typed→map regressions, and chains where every hop re-converts75 without adding anything (class #9). Judge each hop separately: a chain can contain one real76 boundary and two gratuitous ones.77- **Re-checks at trust boundaries are defense, not duplication.** A server re-validating client78 input, or a DB constraint backing an app-level check, is deliberate redundancy across trust79 levels. Class #10 flags re-implemented rules at the *same* trust level — two layers behind the80 same boundary each owning their own copy of the regex, threshold, or parse.81- **Port/impl module pairs and per-plugin modules are conventions**, not fragmentation. Don't82 recommend flattening them in an SSOT report.83- **Deliberate, adjudicated dual vocabularies can exist** (e.g. an ADR chose a flat result type84 with a closed discriminator). Check decision records before flagging; contrast honestly — a85 4-field type with a closed-set kind is not the same disease as a 9-field union with no86 discriminator semantics.8788The credibility of the whole report rests on this section. One overreaching finding ("unify all89the Messages!") teaches the reader to ignore the real ones.9091## Treatment Recipes9293Every confirmed finding routes to exactly one recipe; the recipe determines the disposition:9495| Recipe | When | Notes |96|---|---|---|97| **Codegen** | One side can mechanically generate the other (type → schema, registry → enum file) | Strongest fix; pairs with a *currency test* (guards "forgot to regenerate" — that is a constructive gap a compiler can't close, so the test is legitimate) |98| **Parity guard** | Both sides are real artifacts that cannot share a source (language enum vs DB CHECK constraint) | Include a *red drill*: deliberately desync once and confirm the guard fires |99| **Constant promotion** | Bare string keys in map envelopes crossing layers | Promote to a named constant next to its siblings; both writer and reader reference it |100| **Typed payload** | Shape proliferation / map regressions at seams | Often a phase of a larger contract plan; don't band-aid per-field |101| **Convert at the edge** | Redundant conversion chains | Convert once where the value enters the system; pass one canonical type through the interior; merge hops that add no information |102| **Single rule owner** | Re-implemented derivations | Hoist the rule into one named function/type and make every layer call it; where possible encode the proof in the type (parse, don't validate) so downstream layers cannot re-do the work |103| **Vocabulary close-out** | Word overload, legacy mapping layers | Glossary entry + rename of the cheap side; map function single-sourced or fixtures moved to current vocabulary |104| **Adjudication** | Behavior forks | These need a *decision*, not a patch: unify the behavior, or promote the fork into an explicitly documented contract. Present both options with a default recommendation |105| **Delete the pin** | After any recipe eliminates a copy, delete the parity test that was holding the copies together — its survival is evidence of remaining multi-source |106107## Workflow1081091. **Scope.** Agree on the sweep surface (a module, a contract plane, the whole repo). Note any110 prior sweeps/plans to avoid re-finding adjudicated items.1112. **Map the seams first.** List type-system-unreachable boundaries, then the internal modules that112 independently define or derive the same concepts. Seams are priority entrypoints, not the only113 possible location of findings.1143. **Hunt per symptom class** using the cookbook greps. For each candidate, capture file:line for115 *every* definition/use site — counts matter ("this literal is defined in exactly 2 places",116 "adding one event touches 6 files" is the change-amplification number that lands the point).1174. **Verify producer AND consumer** for anything you might call dead or removable. The118 three-surface discipline: backend producers, frontend/contract consumers, seeds/fixtures.1195. **Adjudicate honestly** (section above). Sort exonerated candidates into the "not counted" note.1206. **Write the report** using `references/output-template.md`: numbered findings, evidence,121 severity, recipe, disposition table, positive list ("already-healthy patterns to copy" —122 naming what the repo already does right makes the report constructive and gives fixes a local123 precedent to imitate).1247. **Execute quick wins if asked** — constant promotions and literal de-duplications are usually125 safe same-day (zero wire change, full test gate). Bigger recipes get routed to plans; behavior126 forks get routed to the user as decisions.127128## Hand off when129130- The finding's root cause is a module-boundary or layering problem → **hai-architecture**.131- A finding needs a new name, or the report turns into a rename list → **hai-naming**.132- The dispositions need to become a phased, verifiable plan → **hai-goal**.133- The user wants to reframe the whole contract surface rather than patch findings → **geju**.134135## What this skill is NOT136137- Not a linter: it reports adjudicated findings with treatment routes, not raw matches.138- Not "unify everything": its credibility comes from the not-counted list as much as the findings.139- Not a wire-migration tool: persisted values are out of bounds; only definition sites move.
hylarucoder