Context Gap
Reach for Context Gap the moment a request feels new and the afternoon feels open.
- The request feels new. Words like "new", "from scratch" or "we need a way to" are the usual signs, and they are the requests where duplicates hide.
- Someone asks for a feature, report, alert or automation. Your first instinct is to start building, and that is the moment to stop and search first.
- You pay for more tools than you can list from memory. A feature you already own may be switched off, and that is the cheapest result there is.
- The codebase or knowledge base is older than your memory of it. Anything you remember about it may have changed since you last looked.
Run it on anything that feels new, including small work. Five minutes is cheap next to a build you did not need.
"Look around first" is advice everybody agrees with and few people follow when a request feels new. Context Gap turns that advice into a fixed routine. Before anything gets built, you write the need down, search four places, and record which of six states the search found. The output is a gap result: the state, the evidence behind it, and the next step that state implies.
Why This Skill Exists
The failure this skill prevents is the duplicate. Someone asks for a feature, it feels new, the afternoon is open, and the build starts. Later someone finds a half-built module from an earlier pilot, or a scheduled job that already scores the same records. The work either repeats what exists or finishes the wrong thing.
The author's working estimate, from the Guild article Trust But Verify, is that about two in five requests land on something that already exists in some form. That is one operator's estimate, not a measured rate. Even if the true rate is lower, the costs are lopsided. A search costs minutes. A duplicate costs the afternoon, plus a second copy that now needs upkeep.
The second failure is the search that is never written down. "I looked around" cannot be checked, cannot be handed to the next person, and does not show which places were skipped. So the skill makes the search produce a result with a fixed set of states. A plain yes or no is too coarse, because "already built" and "partly built" lead to different next steps.
The Four Places
Each place answers a different question, and all four are searched before a state is chosen.
- The codebase holds what was built.
- The knowledge base holds what was decided.
- The paid tools hold what could be switched on.
- The running patterns show how this team builds things.
Each place is searched three ways, in this order: by name, by a key phrase inside the contents, and by the pointers in the project's own notes. A file name that matches is only a candidate until its contents are opened and read. A place that cannot be searched is written as not searched, with its reason, because a skipped place looks exactly like an empty one.
The Six Gap States
Every search ends in exactly one state. The code column applies to code, and the document column applies to documents and plans. The names are the same in both columns, so a result reads the same whatever the work is.
| State | For Code | For Documents and Plans |
|---|---|---|
| NO GAP | The thing exists and works. Use it | The answer is already written down, in full |
| CONFIG | The thing exists and is complete, but must be turned on or pointed at | Most of the answer is in the notes, and the remaining step is to point the reader at it |
| COMPLETION | The thing exists partly. Finishing, deploying or setting it up is the work | A partly written piece exists and needs finishing |
| EXTENSION | Something similar exists next to the need. Extend it | A similar piece exists to adapt |
| PATTERN | Nothing similar exists, but the codebase shows how this kind of thing gets built | A template or pattern exists to follow |
| TRUE GAP | Nothing exists, and no pattern shows the way | Nothing exists, and no template shows the way |
Two rules settle the close calls. Turning something on counts as CONFIG, even when it takes one line of setup, because the thing is already built. Setup and deployment work counts as COMPLETION, because what is left is finishing, not inventing. When two states fit, choose the one closer to existing work, because building a second system carries its own upkeep.
The Gap Result
The result is written last, after the search and the classification, so it records what was found and not what was expected. It has a fixed field order, because the review and close steps after it read those fields by name.
- Date and Need, as written before the search.
- Assumptions, each marked checked or not checked, with the place that checked it.
- Searched: codebase, knowledge base, paid tools, patterns, or each place not searched with its reason.
- Findings: for each one, the place, the name or phrase used, and what it does.
- State, Evidence and Next step.
The next step follows from the state. For NO GAP, use the existing thing, named by its location. For CONFIG, change the one setting, named by file and line where possible. For COMPLETION, finish the named file. Under about 50 lines of real work, finish it directly without a planning document, because a plan costs more than the finish at that size. For EXTENSION, extend the named item, which keeps one system where two would need upkeep. For PATTERN, build the new thing the way the named pattern does. For TRUE GAP, run Debate before any commit, because a true gap is the expensive kind to get wrong.
Where It Sits In The Loop
Context Gap runs before anything gets built. It decides whether to build and what to build. It does not judge whether the plan is any good, and that is the job of Debate, which runs before a commit. Debug reads the findings of a COMPLETION or EXTENSION result when a bug sits in the code those findings name. Wrap-Up records the state of any build beside the build it came before.
"I searched thoroughly" is still a claim. The gap result is the evidence for it, so anyone can open the same places and check the findings.