Count by Sweeping, Never by Memory

The Note Said Three

The session that opened the lineage merge inherited a handoff note describing the work, and the note said the parallel convention was in use in three places. Three apps were converted. Then somebody ran a sweep of the whole tree for anything whose filename matched the pattern, and found a fourth adopter that nobody had listed.

Nothing catastrophic followed — it was converted too. What is worth keeping is the shape of the error, because it is completely ordinary: a count was written down by somebody who knew the system, was inherited as fact by somebody who trusted them, and was wrong by one.

Why Notes Undercount Structurally

A handoff note is written by a person recalling a system. Recall retrieves what is salient — the instances that were interesting, recent, or that the author personally touched. The fourth adopter had been added quietly by a different session, in a repository the note's author had not been working in. It was not forgotten; it was never known.

That is why the failure is structural rather than a lapse. There is no amount of care in note-writing that fixes it, because the note's author cannot enumerate what they never saw. The filesystem can.

Scope taken from a document about the work is always weaker than scope taken from the work itself. Notes, tickets, and inherited summaries are recollections, and recollections are lossy in one direction: they miss, they rarely invent. Before acting on a count, run the sweep that would produce that count from the actual artifacts. It costs one command, and the discrepancy is the whole point of running it.

Sweep by Several Names, Not One

One refinement, learned the same day. A single grep for the component's name finds every site that imports it — which is the right instrument once the convention has a name. It does not find a copy that was renamed on the way in, and hand-copied conventions get renamed constantly, because each app names it after itself.

So the sweep that found the fourth adopter was a filename search on a fragment of the concept, not the exact symbol. In general: sweep by the concept's several plausible names, then by an unusual line of its implementation, then by the symbol. Each instrument fails differently, and a copy that survives all three is genuinely absent.

Code

Three instruments, because each one misses differently·bash

# 1. BY SYMBOL - finds every site that imports the shared component.
#    Right answer once the convention has one name. Blind to any
#    copy that was renamed on the way in, which is what hand-copied
#    conventions always are.
grep -rl "KitPippaSidekick" <each repo's source root>

# 2. BY CONCEPT NAME, case-insensitive, on FILENAMES. This is the
#    one that found the fourth adopter: it had been renamed to the
#    app's own vocabulary, so no symbol search could reach it.
find . -iname '*sidekick*' -not -path '*/node_modules/*'

# 3. BY AN UNUSUAL IMPLEMENTATION LINE. A distinctive constant, CSS
#    variable, or storage key survives renaming, because renaming a
#    file is easy and renaming its guts is not.
grep -rn "--sk-offset-right\|sidekick.width" . \
  --include='*.ts*' --include='*.css'

# The check that closes the loop: every hit from ANY instrument must
# appear in the ledger, and every ledger row must have a hit.
#
#   comm -3 <(sweep_results | sort) <(ledger_rows | sort)
#
# Empty output means the document and the filesystem agree. Anything
# printed is either an unlisted adopter or a ledger row describing
# something that no longer exists - and both are worth knowing.

Exercise

Take any migration currently in progress in your world with a stated scope — 'these six services', 'the four call sites'. Run three sweeps for it: by symbol, by filename concept, and by a distinctive implementation string. Compare the union against the stated scope. If they differ, update the scope document with the number the sweep produced and note where the extra came from.

Hint

The most productive sweep is usually the filename one, because it catches adopters that renamed on the way in, and renaming on the way in is the signature of exactly the copies you most want to find.

The Note Said Three

Why Notes Undercount Structurally

Sweep by Several Names, Not One

Code

External links

Exercise

Progress

Comments 0