no-workarounds

What this skill does

# 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.

```typescript
// 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
```

### Category 2 — LINT: Lint and Warning Suppression

**The signal being silenced:** Static analysis found a real problem.

```typescript
// WORKAROUND: Shooting the messenger
// eslint-disable-next-line @typescript-eslint/no-unused-vars
const result = fetchData();

// @ts-ignore
someFunction(wrongArgs);

// @ts-expect-error - TODO fix later
brokenCall();

// PROPER FIX: Fix what the linter found
fetchData(); // Remove unused binding

someFunction(correctArgs); // Fix the arguments
```

**Gate function:**

```
BEFORE adding eslint-disable, @ts-ignore, @ts-expect-error, or any suppression:
  Ask: "What rule is being violated and WHY?"

  IF the code genuinely violates the rule:
    Fix the code, not the linter
  IF the rule is wrong for this codebase:
    Disable the rule in config (globally), not inline
  IF it's a third-party type issue:
    File an issue, add a minimal typed wrapper
  NEVER suppress a warning without understanding it
```

### Category 3 — SWALLOW: Error Swallowing

**The signal being silenced:** Something failed and the code pretends it didn't.

```typescript
// WORKAROUND: Pretending errors don't exist
try {
  await saveData(payload);
} catch {
  // silently ignore
}

try {
  result = JSON.parse(input);
} catch {
  result = {}; // default to empty - hides corrupt data
}

// PROPER FIX: Handle errors meaningfully
try {
  await saveData(payload);
} catch (error) {
  logger.error("Failed to save data", { error, payload });
  throw new SaveError("Data save failed", { cause: error });
}

const parsed = Schema.decodeUnknownSync(PayloadSchema)(input);
// Throws descriptive error if input is invalid
```

**Gate function:**

```
BEFORE writing a catch block:
  Ask: "What specific errors can occur here?"
  Ask: "What should happen when each error occurs?"

  IF the answer is "ignore it":
    STOP — Ignoring errors hides bugs
  IF the answer is "log it":
    Log AND propagate or handle meaningfully
  IF the answer is "use a default":
    Ensure the default is SAFE and the failure is LOGGED
  NEVER write an empty catch block
  NEVER catch Exception/Error broadly without re-throwing specific types
```

### Category 4 — TIMING: Timing and Lifecycle Hacks

**The signal being silenced:** Code runs in the wrong order or at the wrong time.

```typescript
// WORKAROUND: Racing against the clock
setTimeout(() => {
  element.focus();
}, 100);

await new Promise((resolve) => setTimeout(resolve, 500));
// "wait for state to settle"

await retry(() => checkCondition(), { times: 10, delay: 200 });
// retry loop hiding a race condition

// PROPER FIX: Fix the lifecycle
// Use framework-native lifecycle hooks
useEffect(() => {
  if (ref.current) ref.current.focus();
}, [isVisible]);

// Use proper event-driven coordination
await waitForEvent(emitter, "ready");

// Use condition-based polling (not blind retries)
await waitUntil(() => service.isReady(), {
  timeout: 5000,
  message: "Service failed to become ready",
});
```

**Gate function:**

```
BEFORE adding setTimeout, delay, sleep, or retry loops:
  Ask: "WHY is the timing wrong?"
  Ask: "What event signals that the system is ready?"

  IF there's an event or callback available:
    Use it instead of arbitrary delays
  IF the ordering is wrong:
    Fix the initialization order
  IF it's a test timing issue:
    Use condition-based waiting, never arbitrary sleeps
  NEVER use setTimeout(fn, 0) to "fix" rendering issues
  NEVER use arbitrary delays to "wait for things to settle"
```

### Category 5 — PATCH: Monkey Patching and Runtime Mutation

**The signal being silenced:** The API doesn't do what the code needs.

```typescript
// WORKAROUND: Mutating things you don't own
Array.prototype.customMethod = function () { ... };
Object.defineProperty(window, "fetch", { value: customFetch });
library.internals._privateMethod = replacement;

// PROPER FIX: Composition over mutation
function customOperation<T>(arr: T[]): T[] { ... }
const wrappedFetch = createFetchWrapper(window.fetch);
const adapter = new LibraryAdapter(library);
```

**Gate function:**

```
BEFORE modifying prototypes, globals, or third-party internals:
  Ask: "Does the library provide an extension point?"

  IF yes: Use the official extension mechanism
  IF no: Wrap with composition/adapter pattern
  IF the library is broken: File issue, fork, or find alternative
  NEVER modify objects the code doesn't own
```

### Category 6 — SCATTER: Defensive Duplication

**The signal being silenced:** The data is unreliable at its source.

```typescript
// WORKAROUND: Checking everywhere because source is broken
function renderUser(user: User) {
  const name = user?.name ?? user?.displayName ?? "Unknown";
  const email = user?.email ?? user?.contacts?.email ?? "";
  const id = user?.id ?? user?.userId ?? user?._id ?? "";
  // ... 20 more optional chains
}

// PROPER FIX: Validate once at the boundary
const user = Schema.decodeUnknownSync(UserSchema)(rawData);
// user is now guaranteed to have correct shape

function renderUser(user: User) {
  // No defensive checks needed — schema validated at entry
  return `${user.name} (${user.email})`;
}
```

**Gate function:**

```
BEFORE adding optional chaining (?.) or nullish coalescing (??) deeply:
  Ask: "Why might this value be missing?"
  Ask: "Where does this data enter the system?"

  IF data is unvalidated at entry:
    Add validation at the boundary, remove defensive checks downstream
  IF the type allows undefined but shouldn't:
    Fix the type to be non-optional
  IF it's truly optional:
    Handle the None/undefined case explicitly at the nearest decision point
  NEVER scatter optional chains as a substitute for proper validation
```

### Category 7 — CLONE: Copy-Paste Adaptatio