no-new-abstraction

name	no-new-abstraction
description	Enforces the Rule of Three — a new abstraction requires three existing, real call sites before it is created.
when_to_use	Apply automatically whenever new interfaces, base classes, shared utilities, hooks, composables, or generic wrappers are proposed.

No New Abstraction Skill

Premature abstraction is the most common form of technical debt in AI-generated code. A model that sees two similar things immediately wants to extract a shared interface. That instinct is wrong more often than it is right, and the cost compounds every time a future engineer has to understand the abstraction before they can make their change.

This skill enforces a single rule: a new abstraction requires three real, existing call sites.

The Rule of Three

Before creating any of the following, you must demonstrate three existing call sites that would concretely benefit from the abstraction:

• A new interface or abstract class
• A shared utility or helper function
• A generic wrapper, HOC, or composable
• A base class meant to be extended
• A configuration object meant to be reused across features
• Any function whose primary argument is a callback or strategy

"Call sites" means code that exists right now in the codebase. Not code you are about to write. Not hypothetical future use cases. Not "the next engineer will probably need this."

The Check

When a new abstraction is proposed, run this check and output the result:

## Abstraction Gate: [proposed abstraction name]

### Existing Call Sites Found
1. [file:line] — [one sentence describing how this site would use the abstraction]
2. [file:line] — [one sentence describing how this site would use the abstraction]
3. [file:line] — [one sentence describing how this site would use the abstraction]

### Verdict
[APPROVED — 3 real call sites confirmed]
[BLOCKED — only N call sites found]

If fewer than three call sites exist, output this instead:

## Abstraction Gate: BLOCKED

Only [N] real call site(s) found for [proposed abstraction].

The Rule of Three is not met. Proceed with inline implementation.

When a third real call site emerges naturally, revisit the extraction.
The right time to abstract is after the third duplication, not before the second.

What to Do When Blocked

When the rule blocks an abstraction, implement the logic inline at the call site. Do not create a "temporary" version of the abstraction to work around the gate. Temporary abstractions become permanent ones.

Leave a comment at the inline implementation:

// NOTE: inline by design — extract when 3 real call sites exist (Rule of Three)

The Exception

One valid exception: abstractions required by the framework or language idiom (e.g., React context for global state, an interface required to satisfy a third-party type contract). These must be documented as framework-required, not design-driven. They still require a written justification in the ADR.

Why This Matters

Every abstraction is a contract. Contracts constrain the future. A well-timed abstraction (three proven use cases) is knowledge crystallized into code. A premature abstraction (one use case with guesses about the future) is speculation crystallized into a maintenance burden.

An AI that abstracts eagerly is building a maze for the next human engineer.