search-before-you-build
Search Before You Build — The Repo Usually Has It Already
Section titled “Search Before You Build — The Repo Usually Has It Already”Before writing a query, helper, or check, spend one search looking for it. When the codebase already solves the problem, the existing solution encodes decisions you do not have and will not reinvent — usually recorded in its docstring.
Cheap, in either order:
grep -rn "<the concept>" --include="*.ts" --include="*.cjs" src/ .claude/grep -rln "<the column/field>" services/ packages/If a docstring explains WHY it exists, read it before deciding you need your own.
The discovery protocol is corpus first, grep second (theonekit-unity#533). Before naming a
capability greenfield, sweep the studio’s knowledge-retrieval
corpus (mcp__knowledge-retrieval__doc_search) for prior art — capability not checked out here,
design precedent from a sibling project, or a need you cannot name a grep pattern for — then
ground a hit with local grep (real path, on-disk version). Query technique and reporting
discipline are owned by the t1k-knowledge-retrieval skill; cite it, do not restate it here. A
greenfield / no prior art claim is not valid until the sweep has run and its verdict recorded
(reuse-search: not-found-after-corpus-and-grep +
scope: <swept> | swept: <date> on the adjacent line); MCP absent or unreachable → say so and mark
the finding unverified, never greenfield.
Sweep while you are still choosing — not only when you are about to claim absence. The
paragraph above gates the sweep on a greenfield claim. That gate is necessary, and it fires too
late: an agent weighing three approaches, or naming a capability it intends to build, never
asserts absence, so it never trips the gate — which is precisely how shipped capability gets
rebuilt by someone who only ever proposed building something. Run the sweep as an INPUT to the
option set, at the moment you are choosing between approaches or naming what to build. An option
that duplicates shipped capability is not an option, and “nobody said greenfield” is not evidence
that anybody looked.
Why this is a rule, not a reminder: three real misses in one day each cost more than the
search would have — a rebuilt identity check that shipped wrong for lack of an existing
install-state filter, data pronounced “missing” while it sat in an unselected table column, and a
hand-rolled monitor trusted over the fleet’s own telemetry. Full incident writeups:
docs/search-before-you-build.md.
Narrow exception
Section titled “Narrow exception”The existing implementation is genuinely wrong or unfit. Then fix or extend it rather than adding a rival: two near-identical helpers guarantee they drift, and the one with the docstring is the one people trust.
How to apply, and the full cross-reference list: docs/search-before-you-build.md.