build-fix

name	build-fix
description	Expert skill for resolving build errors with minimal change principle. Use for build failures, type errors, compile errors. Keywords: build, fix, error, compile, typescript, type, resolve.

Dynamic Context

Last build output: !cat .claude/state/last-build-error.log 2>/dev/null | tail -20 || echo "No cached build error"

Build Fix Skill

Purpose

Resolve build/compile errors with minimal changes. Target only build passing - no architecture changes, refactoring, or feature additions.

Core Principle: Minimal change → Build passes → Done. Nothing more.

Activation Triggers

• Build failure (npm run build fails)
• TypeScript compilation error (tsc --noEmit fails)
• Multiple type errors occurring
• CI/CD pipeline build failure
• User explicit request: /build-fix, fix build, compile error

---

Scope Definition

✅ DO Fix (Targets for fixing)

Category	Examples
Type annotations	Missing types, incorrect types
Null/Undefined handling	Optional chaining, nullish coalescing
Import/Export	Missing imports, incorrect paths
Type definitions	Add/modify interface, type
Dependency issues	Missing packages, version conflicts
Config files	tsconfig, eslint configuration errors

❌ DON'T Change (Don't touch)

Category	Reason
Unrelated code	Out of scope
Architecture	Requires separate work
Variable/function names	Refactoring area
Logic flow	Risk of functionality change
Performance optimization	Separate optimization work
Test code	Test fixes are separate

---

Workflow

Step 1: Collect Errors

# TypeScript
npx tsc --noEmit 2>&1 | head -100

# Build
npm run build 2>&1

# ESLint (errors only)
npx eslint src/ --quiet

Step 2: Classify Errors

/build-fix

🔍 Analyzing errors...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Error Summary
┌──────────────────────┬───────┐
│ Category             │ Count │
├──────────────────────┼───────┤
│ Type Inference       │ 5     │
│ Missing Types        │ 3     │
│ Import Errors        │ 2     │
│ Null/Undefined       │ 4     │
│ Config Issues        │ 1     │
└──────────────────────┴───────┘
Total: 15 errors

🎯 Resolution Order:
1. Config Issues (blocks others)
2. Import Errors (dependency chain)
3. Missing Types (foundation)
4. Type Inference (detail)
5. Null/Undefined (safety)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3: Apply Minimal Fixes

🔧 Fixing errors...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[1/15] src/api/user.ts:45
  Error: Property 'id' does not exist on type '{}'
  Fix: Add type annotation

  - const user = {}
  + const user: User = {} as User

[2/15] src/utils/format.ts:12
  Error: Parameter 'date' implicitly has 'any' type
  Fix: Add parameter type

  - function formatDate(date) {
  + function formatDate(date: Date): string {

... (continued)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 4: Verify

✅ Verification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Build:     ✅ PASS
TypeCheck: ✅ PASS (0 errors)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Changes Summary:
- Files modified: 8
- Lines changed: +23, -15
- No architectural changes
- No logic changes

🎯 Build fixed with minimal changes!

---

Common Error Patterns

1. Type Inference Failures

// ❌ Error: Type 'string' is not assignable to type 'number'
const count = "5";  // inferred as string

// ✅ Fix: Explicit type or conversion
const count: number = 5;
// or
const count = Number("5");

2. Null/Undefined Handling

// ❌ Error: Object is possibly 'undefined'
const name = user.profile.name;

// ✅ Fix: Optional chaining
const name = user?.profile?.name;

// ✅ Fix: Nullish coalescing
const name = user?.profile?.name ?? "Unknown";

3. Missing Properties

// ❌ Error: Property 'email' is missing
const user: User = { name: "John" };

// ✅ Fix: Add missing property
const user: User = { name: "John", email: "" };

// ✅ Fix: Make optional in type
interface User {
  name: string;
  email?: string;  // optional
}

4. Import Errors

// ❌ Error: Module not found
import { utils } from "./util";

// ✅ Fix: Correct path
import { utils } from "./utils";

// ✅ Fix: Add missing export
// In utils.ts: export { utils };

5. Generic Constraints

// ❌ Error: Type 'T' is not assignable to constraint
function process<T>(item: T) {
  return item.id;  // Error: Property 'id' doesn't exist
}

// ✅ Fix: Add constraint
function process<T extends { id: string }>(item: T) {
  return item.id;
}

6. React Hook Violations

// ❌ Error: React Hook is called conditionally
if (condition) {
  const [state, setState] = useState();
}

// ✅ Fix: Move hook outside condition
const [state, setState] = useState();
if (condition) {
  // use state here
}

7. Async/Await Issues

// ❌ Error: 'await' only allowed in async function
function fetchData() {
  const data = await api.get();
}

// ✅ Fix: Add async
async function fetchData() {
  const data = await api.get();
}

8. Module Resolution

// ❌ Error: Cannot find module '@/components'

// ✅ Fix: Check tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

---

Fix Strategies

Strategy 1: Type Assertion (Quick but risky)

// Quick fix - use sparingly
const data = response as UserData;

Strategy 2: Type Guard (Safe)

// Safer approach
function isUser(obj: unknown): obj is User {
  return obj !== null && typeof obj === 'object' && 'id' in obj;
}

Strategy 3: Type Narrowing (Recommended)

// Best practice
if (user && user.profile) {
  // TypeScript knows user.profile exists here
}

---

When NOT to Use

Situation	Use Instead
Test failures	/verify → Fix tests
Performance issues	/perf-optimize
Security vulnerabilities	/security-audit
Refactoring needed	/refactoring
Architecture change	/architecture
Add new feature	/feature-planner

---

Integration

With /verify

/build-fix → Build passes
/verify quick → Confirm Build + Type
/verify full → Full quality verification

With /checkpoint

/checkpoint create "before-build-fix"
/build-fix
/verify quick
# If issues: /checkpoint restore "before-build-fix"

CI/CD Integration

# Auto-fix attempt on build failure
- name: Build
  run: npm run build
  continue-on-error: true

- name: Auto Fix
  if: failure()
  run: claude build-fix --auto

---

Commands

Command	Description
/build-fix	Analyze and fix build errors
/build-fix --dry-run	Preview fixes (don't apply)
/build-fix --auto	Auto-fix (no confirmation)
/build-fix <file>	Fix specific file only

---

Output Format

Success

╔══════════════════════════════════════════════════════╗
║              🔧 BUILD FIX COMPLETE                   ║
╠══════════════════════════════════════════════════════╣
║ Errors Fixed: 15/15                                  ║
║ Files Modified: 8                                    ║
║ Lines Changed: +23, -15                              ║
║                                                      ║
║ Build Status: ✅ PASSING                             ║
║ Type Check: ✅ PASSING                               ║
║                                                      ║
║ ⚠️  Reminder: Run /verify for full quality check    ║
╚══════════════════════════════════════════════════════╝

Partial Success

╔══════════════════════════════════════════════════════╗
║              🔧 BUILD FIX PARTIAL                    ║
╠══════════════════════════════════════════════════════╣
║ Errors Fixed: 12/15                                  ║
║ Remaining: 3                                         ║
║                                                      ║
║ ⚠️  Manual intervention needed:                     ║
║ 1. src/complex/module.ts:89 - Circular dependency   ║
║ 2. src/legacy/old.ts:45 - Deprecated API usage      ║
║ 3. src/types/index.ts:12 - Conflicting declarations ║
║                                                      ║
║ 💡 Suggestions:                                      ║
║ - Consider refactoring circular dependency          ║
║ - Update deprecated API calls                       ║
╚══════════════════════════════════════════════════════╝