Skip to content
Skills Library
Programming · Building & coding

fix-build-errors

/fix-build-errors

Use when a build, compilation, or type-check fails — diagnose the error, identify root cause, and apply the minimal fix to get green

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a build, compilation, or type-check fails — diagnose the error, identify root cause, and apply the minimal fix to get green

Original author description

Use when a build, compilation, or type-check fails — diagnose the error, identify root cause, and apply the minimal fix to get green

How it works

  1. When to Use
  2. Prerequisites
  3. Workflow
  4. Examples
  5. Tips
Original SKILL.md headings · 152 lines, 670 words
SKILL.md preview
---
name: fix-build-errors
description: Use when a build, compilation, or type-check fails — diagnose the error, identify root cause, and apply the minimal fix to get green
metadata:
  category: development
  agent_type: task
---

# Fix Build Errors

## When to Use

- Build or compilation fails after code changes
- CI pipeline reports build failures
- TypeScript, ESLint, or other static analysis errors
- Dependency resolution failures after package updates
- Build works locally but fails in CI (or vice versa)

## Prerequisites

- Access to the build command and its output
- The project's build toolchain is installed
- Source control so you can compare against a known-good state

## Workflow

### 1. Capture the Full Error Output

```powershell
# Run the build and capture output — use task agent to keep context clean
npm run build 2>&1 | Out-String
```

Or use the `task` agent for long builds:

```text
task agent_type: "task"
prompt: "Run 'npm run build' and report all errors"
```

### 2. Categorize the Errors

Read errors from **top to bottom** — later errors are often caused by earlier ones.

| Error Type | Example | Typical Fix |
|-----------|---------|-------------|
| **Import/Module** | `Cannot find module 'x'` | Install dependency, fix path |
| **Type** | `Type 'string' not assignable to 'number'` | Fix type annotation or cast |
| **Syntax** | `Unexpected token` | Fix syntax error, check for missing brackets |
| **Lint** | `no-unused-vars` | Remove unused variable or disable rule |
| **Config** | `Invalid tsconfig option` | Fix config file |
| **Dependency** | `Peer dependency not met` | Install or update package |

### 3. Fix the Root Cause (Not Symptoms)

```powershell
# Find the first error — it's usually the root cause
npm run build 2>&1 | Select-String "error" | Select-Object -First 5

# Navigate to the file and line
# Use view tool to see context around the error
```

For import errors:

```powershell
# Check if the module exists
glob pattern="**/*moduleName*"

# Check if it's installed
npm ls module-name 2>&1
```

For type errors:

```powershell
# See the full type definition
grep -rn "interface|type" --include="*.ts" -A 5 src/ | Select-String "TypeName"
```

### 4. Apply the Fix

Use `edit` for surgical changes to specific lines:

```text
edit path: "src/broken-file.ts"
old_str: "const x: string = 42;"
new_str: "const x: number = 42;"
```

### 5. Verify the Fix

```powershell
# Rebuild — should succeed now
npm run build 2>&1 | Select-Object -Last 10

# Run tests to ensure the fix didn't break behavior
npm test 2>&1 | Select-Object -Last 10
```

### 6. Handle Cascading Errors

If fixing one error reveals more:

1. Rebuild after each fix
2. Address new errors from top to bottom
3. If the error count isn't decreasing, you may be fixing symptoms — step back and find the root cause

## Examples

### Missing Dependency

```powershell
# Error: Cannot find module 'lodash'
npm install lodash
npm install --save-dev @types/lodash  # for TypeScript

npm run build
```

### TypeScript Strict Mode Errors After Upgrade

```powershell
# Find all strictNullChecks errors
npx tsc --noEmit 2>&1 | Select-String "possibly 'null'" | Measure-Object -Line

# Fix them one file at a time, starting with leaf modules (no imports from your code)
npx tsc --noEmit 2>&1 | Select-String "possibly 'null'" | Select-Object -First 3
```

### CI vs Local Mismatch

```powershell
# Check Node/npm version differences
node --version
npm --version

# Check for OS-specific path issues
grep -rn "\\\\" src/ --include="*.ts"  # Windows backslashes in code

# Check for missing environment variables
grep -rn "process.env" src/ --include="*.ts" | Select-String -NotMatch "NODE_ENV"
```

## Tips

- **Fix the first error first** — many later errors are caused by earlier ones
- Use `task` agent to run builds — it returns brief output on success, full output on failure
- After fixing, always run the full test suite, not just the build
- If a dependency update caused the break, check its changelog for breaking changes
- For persistent issues, compare against the last known-good commit:

  ```powershell
  git --no-pager log --oneline -10
  git --no-pager diff <last-good-commit> -- src/
  ```

- Keep `tsconfig.json` / build configs in source control so you can diff changes

Versions

The database has no other skills named fix-build-errors.

Database snapshot: 13.11.2026 · package version 5f302145e401 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100build-fix
    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.
  • 100actions-debugging
    Use when a GitHub Actions workflow fails — diagnose the run log, identify the root cause, and apply a targeted fix
  • 95rc-diagnose
    Diagnoses a bug or behavior to root cause, then fixes and verifies. Use for any failure. Do not use to review a diff (rc-code-review).
  • 90build-failure
    Use when compilation, typechecking, bundling, or another build step fails. Read the first error, isolate the hunk, and do not run tests until the build is green. Distinct from a test regression: the code never ran.
  • 100diagnose
    Trace a bug, regression, failure, or crash to an evidence-backed root cause, then hand off or apply the minimal fix. Use when the cause is unknown or disputed, or when auditing where the same defect recurs.
  • 100diagnose
    Trace a bug, regression, failure, or crash to an evidence-backed root cause, then hand off or apply the minimal fix. Use when the cause is unknown or disputed, or when auditing where the same defect recurs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.