Build Fix

Overview

Build errors block everything. Fix them fast, fix them small, fix nothing else.

Core principle: Fix ONLY what is broken. A build fix is not an opportunity to refactor, add features, or improve architecture. Touch the minimum lines required to restore a passing build.

Violating the letter of this process is violating the spirit of build fixing.

The Iron Law

MINIMAL DIFF, NO ARCHITECTURE CHANGES — FIX WHAT'S BROKEN, NOTHING MORE

If your diff touches lines unrelated to the error, you are not build-fixing. You are refactoring. Stop.

No exceptions:

• "While I'm here, I'll clean up..." → No. Separate PR.
• "This would be better as..." → No. Separate issue.
• "The real problem is the architecture..." → No. File an issue, fix the build now.

When to Use

Use for ANY build/compilation failure:

• TypeScript compiler errors (tsc --noEmit failures)
• Import/export resolution errors
• Dependency version mismatches or missing packages
• Configuration errors (tsconfig, webpack, vite, etc.)
• CI/CD build pipeline failures
• Module not found errors

Use this ESPECIALLY when:

• Build is red and blocking the team
• CI pipeline is failing on compilation
• Dependency update broke the build
• Merge conflict left broken imports

Do NOT use when:

• Tests fail but build succeeds → use systematic-debugging
• You want to improve code quality → use refactoring
• You want to add features → use brainstorming + TDD
• Runtime errors, not compile-time → use error-analysis

Error Classification

First, classify the build error:

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Read the Error

BEFORE attempting ANY fix:

1. Read the FULL error output

• Don't skim — read every line
• Note the error code (e.g., TS2345)
• Note the exact file and line number
• Note what the compiler expected vs. what it got

1. Classify the error (see table above)

• What class does this error belong to?
• Is it a single error or a cascade?
• Cascading errors: fix the FIRST error only, then re-run

1. Count the errors

• One error? Fix it directly.
• Many errors, same root cause? Fix the root, not each symptom.
• Many unrelated errors? Fix one at a time, verify after each.

Phase 2: Identify Root Cause

Find the MINIMUM change needed:

1. Check recent changes

   git diff HEAD~1        # What changed?
   git log --oneline -5   # Recent commits

1. Trace the error to its source

• TypeScript error at line 42? Read line 42.
• Import error? Check if the export exists at the source.
• Dependency error? Check package.json versions.

1. Identify the scope

• How many files need to change?
• If more than 3 files → question whether this is truly a build fix
• If it requires new files → this is not a build fix, it's a feature

Phase 3: Minimal Fix

Apply the SMALLEST possible change:

1. One fix at a time

• Change one thing
• Don't bundle fixes
• Don't "improve" surrounding code

1. Common minimal fixes

   // TypeScript: TS2345 - Type mismatch
   // BAD: Rewrite the function with new types
   // GOOD: Add the correct type annotation or assertion
   const value = data as ExpectedType;

   // TypeScript: TS2532 - Possibly undefined
   // BAD: Refactor to eliminate the possibility
   // GOOD: Add null check or optional chaining
   const name = user?.name ?? 'default';

   // Import: Cannot find module
   // BAD: Restructure the module system
   // GOOD: Fix the import path
   import { Thing } from './correct/path';

   // Dependency: Missing peer dependency
   // BAD: Upgrade the entire dependency tree
   // GOOD: Install the specific missing package
   // $ yarn add missing-package@^required.version

1. What NOT to do

• Do NOT rename variables for "clarity"
• Do NOT extract functions for "reusability"
• Do NOT add error handling beyond what's needed
• Do NOT update unrelated dependencies
• Do NOT change code formatting

Phase 4: Verify

Confirm the build passes:

1. Run the build command

   # Run the same command that failed
   yarn build          # or npm run build
   tsc --noEmit        # TypeScript check

1. Run tests to ensure no regressions

   yarn test           # or npm test

1. Check the diff

   git diff

• Is every changed line directly related to the error?
• Did you touch anything unrelated? Revert it.
• Is the diff as small as possible?

1. If build still fails

• Read the NEW error message
• Is it the same error? → Your fix was wrong. Revert.
• Is it a different error? → Return to Phase 1 for the new error.
• Do NOT stack fixes without verifying between each one.

Red Flags — STOP and Return to Phase 1

If you catch yourself thinking:

ALL of these mean: STOP. You are no longer build-fixing.

Common Rationalizations

Scope Guard

Before committing, verify your changes pass the scope guard:

For EACH changed line, ask:
  "Would the build fail without this specific change?"

  YES → Keep it
  NO  → Revert it

If any changed line fails the scope guard, you have scope creep. Remove it.

Quick Reference

Related Skills

• `error-analysis` — For classifying and understanding error messages (Phase 1)
• `systematic-debugging` — For runtime bugs, not compile-time errors
• `verification-before-completion` — For confirming the fix before claiming success
• `refactoring` — For when you actually WANT to improve structure (not during build fix)