no-workarounds

No Workarounds

The Fundamental Law

A WORKAROUND IS A LIE TOLD TO THE COMPILER.
It makes the symptom disappear while the disease spreads.

A workaround is any change that makes a problem stop manifesting without addressing why the problem exists. Workarounds are not fixes. They are deferred failures with compound interest.

Philosophical foundation: Read references/philosophical-foundations.md for the engineering principles behind this skill, drawn from Toyota's Jidoka, Fowler's Technical Debt Quadrant, Torvalds' "good taste," and the Broken Windows Theory.

The Workaround Detection Gate

BEFORE writing or proposing ANY fix:

1. STATE the problem clearly
2. ASK: "Why does this problem exist?" (not "How do I make it stop?")
3. TRACE to root cause (use systematic-debugging skill)
4. ASK: "Does my proposed fix address the ROOT CAUSE?"
5. ASK: "Would this fix be necessary if the code were correct?"
6. ASK: "Am I silencing a signal or fixing a source?"

IF any answer reveals symptom-patching:
  STOP — Redesign the fix to address root cause

IF root cause is in external code or truly unfixable:
  Document why, add defensive validation, and mark with WORKAROUND comment
  (See "The Escape Valve" section below)

The Seven Categories of Workarounds

Category 1 — TYPE: Type System Evasion

The signal being silenced: The type system is telling the code is wrong.

// WORKAROUND: Lying to the compiler
const value = response.data as UserProfile;
const config = {} as AppConfig;
function process(input: any) { ... }

// PROPER FIX: Make types truthful
const value: UserProfile | undefined = response.data;
if (!value) throw new Error("Missing user profile");

const config: AppConfig = { theme: "light", locale: "en" };

function process(input: UserProfile) { ... }

Gate function:

BEFORE using `as`, `any`, `unknown` cast, or `!` (non-null assertion):
  Ask: "Why doesn't the type match?"

  IF the data shape is genuinely unknown:
    Use runtime validation (Schema, Zod, or type guards)
  IF the type is wrong:
    Fix the type definition
  IF the API returns unexpected shape:
    Fix the API contract or add a validation layer
  NEVER use type assertions to bypass compiler errors