build-fix

name	build-fix
description	Use when build fails, TypeScript errors appear, or compilation breaks. Minimal diff fixes only — no refactoring, no architecture changes.
user-invocable	true
allowed-tools	Read, Edit, Grep, Glob, Bash

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:

Class	Symptoms	Typical Minimal Fix
TypeScript Error	TS2345, TS2339, TS7006, TS2532	Add type annotation, null check, or correct type
Import Error	Cannot find module, has no exported member	Fix path, add missing export, correct import name
Dependency Error	Version mismatch, missing peer dep, lockfile conflict	Align version, install missing package
Config Error	tsconfig.json invalid, env var missing, wrong target	Fix config value, add missing variable
Syntax Error	Unexpected token, missing bracket	Fix syntax at reported location

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

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

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

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

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

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

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

2. Run tests to ensure no regressions

   yarn test           # or npm test
   

3. 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?

4. 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:

Thought	Reality
"While I'm fixing this, I'll also..."	Build fix. Nothing else.
"This function should really be..."	File an issue. Fix the build.
"The types are all wrong, let me redesign..."	Fix the ONE type error. Not all types.
"I need to add a new abstraction..."	No new abstractions in a build fix.
"Let me upgrade this dependency to latest..."	Only change the version if it fixes the error.
"This code is messy, let me clean up..."	Messy code that compiles > clean code in a broken build.
"The architecture caused this, so I should..."	Architecture changes are not build fixes.

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

Common Rationalizations

Excuse	Reality
"The refactor prevents future build errors"	Future prevention is a separate task. Fix now.
"It's just a small improvement"	Small improvements compound into large diffs.
"The code is already open in my editor"	Being convenient doesn't make it a build fix.
"No one will review a 1-line PR"	1-line PRs are the BEST PRs. Ship it.
"I need to understand the whole module"	You need to understand the error. Not the module.
"The dependency is outdated anyway"	Outdated but compiling > updated and broken.

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

Phase	Key Activity	Success Criteria
1. Read	Read full error, classify, count	Know WHAT is broken
2. Identify	Check changes, trace source	Know WHERE and WHY
3. Fix	Smallest possible change	Minimal diff applied
4. Verify	Build passes, tests pass, diff is clean	Build green, no extras

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)