<!-- SYNCED COPY — do not edit here.
Canonical: common-docs/skills/one-canonical/SKILL.md
This file is distributed to every consuming repo by
common-docs/meta/scripts/sync_skills.py. Edit the canonical, run the
sync, and commit each repo. Edits made here are overwritten and lost. -->
one-canonical
The rich-content census took three rounds and each one still found surfaces the last missed. Every step below ends on a check; skipping one is the failure.
1. Start THE LIST before you search
Create one list file the first minute (<project>/LIST.md or the project's register). Every instance
you find, in any round, by anyone, goes on it immediately: what · where (file / table / route / repo)
· how found · status. Never rebuild it from memory or from a summary. A find that is not on the list
was not found.
Done when: the list exists and every later step writes to it.
2. Research until the finds stop
Keyword grep is round one, never the last round. Each round uses a DIFFERENT method:
- enumerate, don't search: every route, every table, every package, every repo (not only this one);
- walk the import graph, the database (live columns, triggers, row counts, never estimates), overlays,
windows, registries loaded by string key;
- read how each copy actually behaves, not just where it is.
Where copies do the same job differently, list every way on the list and pick a winner per capability.
Build the canonical one CLEAN from the winners: never promote the best existing copy and patch it.
Done when: a round using a new method adds nothing to the list.
3. Migrate one by one from the list
Work the list top to bottom. Each item: move it, verify it on its real surface, mark it done with the
proof. No bulk "all migrated" claims. Before moving each item, screenshot it in place and apply
canonicalize without destroying: an ordinary copy is
replaced; a copy that is visibly better in its spot is adopted into the canonical piece (feature,
option or new primitive) after one simple question to Arman with before/after links. Only then is
the old copy deleted, not left beside the new one.
Done when: every row is done-with-proof or explicitly out of scope with a reason.
4. Tear it apart before you believe it
When you think you are done, dispatch agents that did NOT build it and do NOT get your list: they
search every codebase from scratch for anything still doing the job the old way. Every find goes on the
list and back through step 3.
Done when: an independent sweep returns nothing new.
5. Look for what nobody called this before
Charge at least one agent to think outside the box: what does this same job under another name? (The
assistant answer is a note. A flashcard front is rich content. A system prompt is a document.) Anything
that fits joins the list.
Done when: that agent's finds are on the list and migrated or ruled out with a reason.
6. Lock the door
Add a guard that fails on any NEW use of an old copy, with a baseline that only shrinks, proven
failing-then-passing (forcing-function-tests).
Done when: the guard is in the release gates and its self-test goes red then green.