Skip to main content

​
Overview

The build-error-resolver agent is an expert build error resolution specialist. Its mission is to get builds passing with minimal changes — no refactoring, no architecture changes, no improvements.
​
name
string
default:"build-error-resolver"
Agent identifier
​
model
string
default:"sonnet"
Uses Claude Sonnet for efficient error resolution
​
tools
array
Available tools: Read, Write, Edit, Bash, Grep, Glob

​
When to Use

Build fails with TypeScript errors
Compilation errors prevent development
Type inference issues
Module resolution errors
The build-error-resolver agent activates PROACTIVELY when build fails or type errors occur.

​
Core Responsibilities

  1. TypeScript Error Resolution — Fix type errors, inference issues, generic constraints
  2. Build Error Fixing — Resolve compilation failures, module resolution
  3. Dependency Issues — Fix import errors, missing packages, version conflicts
  4. Configuration Errors — Resolve tsconfig, webpack, Next.js config issues
  5. Minimal Diffs — Make smallest possible changes to fix errors
  6. No Architecture Changes — Only fix errors, don’t redesign

​
Diagnostic Commands

npx tsc --noEmit --pretty
npx tsc --noEmit --pretty --incremental false   # Show all errors
npm run build
npx eslint . --ext .ts,.tsx,.js,.jsx

​
Workflow

​
1. Collect All Errors

  • Run npx tsc --noEmit --pretty to get all type errors
  • Categorize: type inference, missing types, imports, config, dependencies
  • Prioritize: build-blocking first, then type errors, then warnings

​
2. Fix Strategy (MINIMAL CHANGES)

For each error:
  1. Read the error message carefully — understand expected vs actual
  2. Find the minimal fix (type annotation, null check, import fix)
  3. Verify fix doesn’t break other code — rerun tsc
  4. Iterate until build passes

​
3. Common Fixes

ErrorFix
implicitly has 'any' typeAdd type annotation
Object is possibly 'undefined'Optional chaining ?. or null check
Property does not existAdd to interface or use optional ?
Cannot find moduleCheck tsconfig paths, install package, or fix import path
Type 'X' not assignable to 'Y'Parse/convert type or fix the type
Generic constraintAdd extends { ... }
Hook called conditionallyMove hooks to top level
'await' outside asyncAdd async keyword

​
Examples

​
Fix: Implicit Any Type

// ERROR: Parameter 'user' implicitly has an 'any' type
function greet(user) {
  return `Hello, ${user.name}`;
}

// FIX: Add type annotation
interface User {
  name: string;
}

function greet(user: User) {
  return `Hello, ${user.name}`;
}

​
Fix: Possibly Undefined

// ERROR: Object is possibly 'undefined'
const userName = users.find(u => u.id === userId).name;

// FIX: Optional chaining
const userName = users.find(u => u.id === userId)?.name;

// OR: Null check
const user = users.find(u => u.id === userId);
if (!user) throw new Error('User not found');
const userName = user.name;

​
Fix: Module Not Found

// ERROR: Cannot find module '@/lib/utils'
import { formatDate } from '@/lib/utils';

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

// OR: Use relative import
import { formatDate } from '../../lib/utils';

​
Fix: Type Mismatch

// ERROR: Type 'string' is not assignable to type 'number'
const userId: number = req.params.id;

// FIX: Parse string to number
const userId: number = parseInt(req.params.id, 10);

​
DO and DON’T

  • Add type annotations where missing
  • Add null checks where needed
  • Fix imports/exports
  • Add missing dependencies
  • Update type definitions
  • Fix configuration files
  • Refactor unrelated code
  • Change architecture
  • Rename variables (unless causing error)
  • Add new features
  • Change logic flow (unless fixing error)
  • Optimize performance or style

​
Priority Levels

LevelSymptomsAction
CRITICALBuild completely broken, no dev serverFix immediately
HIGHSingle file failing, new code type errorsFix soon
MEDIUMLinter warnings, deprecated APIsFix when possible

​
Quick Recovery

# Nuclear option: clear all caches
rm -rf .next node_modules/.cache && npm run build

# Reinstall dependencies
rm -rf node_modules package-lock.json && npm install

# Fix ESLint auto-fixable
npx eslint . --fix

​
Success Metrics

npx tsc --noEmit exits with code 0
npm run build completes successfully
No new errors introduced
Minimal lines changed (< 5% of affected file)
Tests still passing

​
When NOT to Use

Use different agents for these scenarios:
  • Code needs refactoring → use refactor-cleaner
  • Architecture changes needed → use architect
  • New features required → use planner
  • Tests failing → use tdd-guide
  • Security issues → use security-reviewer

​
Usage Example

# Invoke build-error-resolver directly
ask build-error-resolver "Fix all TypeScript errors"

# Or let it activate automatically
npm run build  # Fails with errors
# → build-error-resolver activates and fixes errors
Fix the error, verify the build passes, move on. Speed and precision over perfection.