Add typescript-compiler-blindspots skill

[MajorLift]

Adds a typescript-compiler-blindspots skill under domains/testing.

The problem

A hand-written TypeScript type is a claim about a value's shape, and it compiles whether or not the claim is true. So a green tsc tells you the code is well-formed, not that the types are correct — and in a partially-migrated repo it often cannot tell you at all: with checkJs off, a type written for a function whose callers are still .js is checked against nothing and can drift indefinitely.

That is exactly the gap JS→TS migration PRs live in, and reviewing them by eye does not close it.

What the skill does

• Makes the claim falsifiable with a two-arm substitution proof at a fixed commit — no rebase, no merge boundary:
  • Arm A — the PR as written. Must be silent; a noisy baseline means Arm B is unattributable and the run is inconclusive, not a pass.
  • Arm B — same tree, hand-written type swapped for the derived one, exercised as the real call site exercises it. Each new diagnostic is a disagreement the hand-written type concealed.
• Gives a search order for the authoritative source — the call site (including a JSDoc @type on a JS caller, which sometimes already names it), SomeController['method'], a package already imported in the file, the sender of a message, ReturnType<typeof selector>, the @types/* declaration. Plus the case that matters for honesty: when no source exists, hand-writing is correct and gets recorded as a cleared falsifier.
• Names the four divergence shapes that cover nearly every real finding — widening, dropped nullability, duplication, placeholder (Record<string, unknown>).
• Audits the second axis: typing edits that quietly change runtime behavior — a literal swapped for a runtime enum lookup, a deleted default parameter, a call made optional so a throw becomes a silent no-op, a widened local propping up a check. Each with a reachability verdict rather than a "might be a bug."
• Weights findings by observability — an unlikely failure inside a swallowed catch { captureException } can outrank a likely one in a loud path, because nothing goes red.

Contents

File
skill.md	the method, the search order, the divergence taxonomy, the runtime-behavior pass
scripts/substitution-ab.sh	runs both arms; refuses to read Arm B if Arm A is not silent
references/false-negatives.md	the standing blind spots, each with a verified demonstration
references/worked-example.md	12 hand-written types on a real migration PR → 5 confirmed divergences, 5 cleared
references/metamask-extension.md	repo notes: heap, probe location, checkJs off, authoritative-source lookup table

Added since first review: the standing blind spots

The skill originally covered one class — types hand-written to restate a source that already has one, found by substituting the derived type and diffing tsc output. references/false-negatives.md adds the class that needs no PR to find, because it is a property of the language and the config rather than of any diff:

• Unsoundness: index access typed as if the element always exists, ?: accepting an explicit undefined, bivariant method parameters, covariant arrays, excess-property checks that fire only on fresh literals, structural typing erasing domain distinctions.
• Boundaries: any absorbing any annotation, ambient declare module believed unconditionally, external data asserted rather than validated, JS callers checked not at all.
• Config: skipLibCheck, exclude, include, checkJs — and the one worth saying out loud, that noEmit plus a transpiling bundler means a type error breaks a CI job, not the build.

Each is demonstrated, not asserted. The reference carries a file whose ten blocks are all genuinely wrong; typechecked against metamask-extension at 7fafda0 with that repo's own tsconfig.json, tsc reports zero errors on every one.

The rename follows from this: type-proof described what tsc already does. The subject is the complement — what it cannot do, because it checks declarations for internal consistency and never for correspondence to the source they restate.

Notes for reviewers

• maturity: experimental — the method is proven on one PR (metamask-extension#44397), not yet across repos.
• Extension specifics are in references/, not repos/, deliberately: a repos/ subdir containing only an extension overlay would make the skill skip installs for mobile and core. The technique applies to all three.
• Review-side companion to the write-side guideline proposed in contributor-docs#178.
• yarn test passes (41/41) and metamask-skills list --domain testing --maturity experimental discovers the skill.

The part I would push back on hardest

The worked example includes a claim the probes refuted — a provider return type I first read as unsound, which turned out fine once an unrelated nullability error one property ahead of it was isolated. It is in there on purpose: a substitution sweep that only ever confirms is indistinguishable from one that never isolated anything, so the skill requires reporting clearances alongside findings.