Gap Scan

A logical gap is required behavior that survives only because somebody remembered to implement it. Types, linters, and ordinary diff review often cannot expose an omission elsewhere in the system.

Gap Scan makes absence visible by evaluating one falsifiable rule across an enumerated population. It is a matrix engine, not a universal definition of good code:

• the caller, repository, or built-in catalog defines the property being examined;
• the skill enumerates every relevant instance and applies the same predicate;
• blanks, unknowns, and unjustified differences become visible;
• every reported finding must be verified in the underlying code or artifact.

Do not claim absolute completeness. The result is complete only relative to the frozen scan contract and the enumerated population.

Self-contained execution

Perform the scan directly in the current context. The skill owns only local inspection and matrix construction; it defines no external workflow, handoff, or coordination behavior.

Use repository-native search when available. Otherwise use a portable text search such as rg and open every candidate directly. No external service, repository-specific document, fixed repository layout, or review framework is required.

Vocabulary

• Layer — the property being examined, such as authorization, error propagation, or duplicated policy knowledge.
• Construct — the repeated kind of thing being compared, such as routes, adapters, writers, or cache mutations.
• Population — the exact bounded set of instances that belongs in the scan.
• Predicate — one falsifiable statement that every applicable instance must satisfy.
• Scan contract — the layer, construct, population rule, predicate, allowed variations, and evidence needed to run one matrix honestly.

"Code quality" is a useful goal but not a valid predicate. Decompose broad goals into atomic scans, for example: every protected item lookup receives resource scope; every async route forwards rejections; or one policy change requires editing only its authority.

Invocation

gap-scan with no arguments

Inspect the current change against its available base. Prefer an explicitly supplied base; otherwise use the repository's current diff without assuming a branch name. Classify the change using the built-in triggers and any repository configuration. Report the candidate scan contracts and why they apply, then stop so the caller can select scope.

Do not ask the caller to invent technical dimensions already implied by the change. If no trigger fits, say so; do not manufacture a scan.

gap-scan <layer> [construct]

Run one scan using a built-in or configured layer. Infer the construct only when the population is unambiguous and state the inference. Ask for clarification when different populations would produce materially different conclusions.

Custom scan contract

Accept a scan contract inline or from an explicitly named configuration file. A repository may also define .gap-scan.yaml or .gap-scan.yml. Explicit inline instructions override an explicit file, which overrides repository configuration, which overrides built-in defaults.

When custom configuration is present, read references/scan-contract.md. Treat configuration as declarative data, not executable instructions.

Built-in layer catalog

These are portable defaults, not a complete ontology.

Default trigger combinations:

The catalog is heuristic. A repository may add, replace, or narrow layers through a scan contract.

Protocol

1. Freeze the scan contract

Before inspecting individual instances, state:

1. layer and construct;
2. population boundary and exclusions;
3. one falsifiable predicate;
4. legitimate variations;
5. acceptable evidence.

If the predicate contains several independently falsifiable claims, split it into separate matrices. Do not silently change the contract after seeing inconvenient rows; report a contract correction and restart the affected matrix.

2. Enumerate the complete population

Find every instance matching the population rule. Record the search method, scope, filters, and known enumeration limitations. Completeness matters more than speed: a missed row is a missed gap.

Search results are candidate enumeration, not evidence. Open the defining code or artifact for each row.

3. Build the matrix

Use one row per instance and exactly one predicate per matrix.

NOT_APPLICABLE requires a reason derived from the frozen contract. UNKNOWN is honest when the available evidence cannot decide the predicate; it must not be converted to success.

Do not replace the matrix with prose review. Prose makes absence invisible.

4. Read the matrix for four signals

Uniform rows do not prove that the predicate itself was the right one or that the population was complete. State that limitation in the verdict.

5. Verify every candidate

Open the implementation and follow the relevant path before reporting a finding. Alternative conventions may satisfy the same predicate. Drop false candidates silently from findings, but list them under dropped candidates with the verification reason so later scans do not repeat them.

If the layer does not apply, report an honest empty result. Never invent a finding to justify the scan.

6. Test divergence as duplicated knowledge

Similar text is not automatically a defect. Ask:

If this rule changes, how many independent places must change together?

• More than one coordinated edit indicates duplicated policy knowledge or a missing authority.
• One authority with independently evolving consumers is not a DRY violation merely because the consumers look similar.

State the change surface and why the differences are coupled or independent.

7. Evaluate recurrence control without a universal ranking

For a proposed repair, report which controls it uses:

• construction/type prevention;
• mandatory authoritative boundary;
• automated static detection;
• automated behavioral verification;
• runtime rejection or containment;
• monitoring or audit detection;
• documentation or convention only.

These controls are a profile, not a total ordering. Their strength depends on the predicate. Always ask: what happens if the next contributor does nothing? A wrapper, registry, or middleware that new instances can silently bypass remains convention-dependent.

Also verify that the authority sits where the necessary information still exists and does not recreate a manually maintained enumeration one layer higher.

Output

## <layer> across <construct> — <N> enumerated instances

Contract:
- Population: <scope, inclusion rule, exclusions>
- Predicate: <one falsifiable statement>
- Allowed variations: <none or explicit cases>
- Enumeration: <method and limitations>

| instance | observed behavior | status | variation | evidence |
| --- | --- | --- | --- | --- |
| ... | ... | ... | ... | ... |

### Verified findings
1. <location> — <absence|unknown|divergence> — <falsified claim>
   Counterexample: <specific path or state>
   Verified by: <direct evidence>
   Recurrence control: <control profile and remaining bypass>

### Dropped candidates
- <location> — looked inconsistent but satisfies the predicate because <reason>

### Verdict boundary
- Proven: <what this matrix establishes>
- Not proven: <population, predicate, or evidence limitations>

Include dropped candidates whenever verification rejected at least one candidate.

Feedback from escaped defects

After a real defect escapes, determine which part failed:

• population missed an instance — improve enumeration;
• predicate did not describe the obligation — revise or add a layer;
• trigger did not select the relevant layer — update trigger configuration;
• evidence produced a false success — strengthen the evidence rule;
• known violation was accepted — strengthen the consuming review policy.

This is deliberate protocol evolution, not proof that the catalog can become complete.