Original files: agents/build-error-resolver.md + commands/build-fix.md

Build Error Resolution

Overview

A workflow for fixing build and type errors with minimal changes. Core principle: fix the error, verify the build passes, move on. No refactoring, no architecture changes, no new features. Supports multi-language build system detection.

--------|---------------| | package.json with build script | npm run build or pnpm build | | tsconfig.json (TypeScript) | npx tsc --noEmit | | Cargo.toml | cargo build 2>&1 | | pom.xml | mvn compile | | build.gradle | ./gradlew compileJava | | go.mod | go build ./... | | pyproject.toml | python -m py_compile or mypy . |

Workflow

1. Collect All Errors

• Run the build command and capture stderr
• Group errors by file path
• Sort by dependency order (fix imports/types before logic errors)
• Count total errors for progress tracking

2. Fix Loop (One Error at a Time)

For each error:

1. Read the file -- See error context (10 lines around the error)
2. Diagnose -- Identify root cause (missing import, wrong type, syntax error)
3. Fix minimally -- Smallest change that resolves the error
4. Re-run build -- Verify the error is gone and no new errors introduced
5. Move to next -- Continue with remaining errors

3. Common Fixes

Guardrails

Stop and ask the user if:

• A fix introduces more errors than it resolves
• The same error persists after 3 attempts
• The fix requires architectural changes
• Build errors stem from missing dependencies (need install commands)

DO and DON'T

DO:

• Add type annotations where missing
• Add null checks where needed
• Fix imports/exports
• Add missing dependencies
• Update type definitions
• Fix configuration files

DON'T:

• Refactor unrelated code
• Change architecture
• Rename variables (unless causing error)
• Add new features
• Change logic flow (unless fixing error)
• Optimize performance or style

Recovery Strategies

Nuclear Options

# Clear all caches
rm -rf .next node_modules/.cache && npm run build

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

# Auto-fix ESLint issues
npx eslint . --fix

Priority Levels

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

• 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