# Resolve Typescript Build Errors

> Resolve TypeScript compilation errors by grouping diagnostics, fixing root causes first, applying safe fix patterns, and verifying via a clean compile.

- Skill: `willyu1007/resolve-typescript-build-errors` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add willyu1007/resolve-typescript-build-errors`
- Raw SKILL.md: https://api.skillmd.com/api/skills/willyu1007/resolve-typescript-build-errors/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: willyu1007 (https://skillmd.com/u/willyu1007)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/willyu1007/resolve-typescript-build-errors

---


# Resolve TypeScript Build Errors

## Purpose
Fix TypeScript compilation errors efficiently by grouping diagnostics, addressing root causes first, and verifying with a clean compile.

## When to use
Use this skill when:
- `tsc` (or your build) fails with type errors
- A refactor introduced widespread type breakage
- You upgraded dependencies and type definitions changed
- CI fails on TypeScript checks

## Inputs
- The full TypeScript diagnostic output (copy/paste is fine)
- The command used to reproduce the errors (or the CI step)
- The scope of the change (which packages/modules were modified)
- Any constraints (do not refactor, minimal fix, etc.)

## Outputs
- A prioritized error list grouped by root cause
- Code changes that resolve the errors with minimal collateral changes
- Verification evidence: which command(s) now pass

## Core rules
- You MUST fix root causes before chasing downstream errors.
- You SHOULD avoid `@ts-ignore` and unsafe casts; if used, you MUST justify and isolate them.
- You MUST verify by re-running the TypeScript check until it is clean.

## Steps
1. **Collect diagnostics (complete, not partial)**
   - Capture the full error output (not just the first error).
   - Identify which build target is failing (app, server, library).
   - Record the reproduction command.

2. **Group errors by root cause**
   - missing exports/imports
   - signature/assignment incompatibilities
   - property/shape mismatches
   - `undefined`/`null` strictness
   - `unknown` flows
   - generic constraint failures
   - module resolution/tsconfig issues

3. **Prioritize the highest-leverage fixes**
   - Start with missing exports/paths (often unlocks many errors).
   - Then fix shared types/interfaces used widely.
   - Then fix local call sites.

4. **Apply minimal, safe fix patterns**
   - Use the triage worksheet to track groups and progress.
   - Use the common fix patterns reference for typical error categories.
   - After each group fix, re-run the reproduction command to confirm you are reducing errors.

5. **Verify to clean**
   - Re-run the same TypeScript check until it produces zero errors.
   - If changes touched runtime logic or boundaries, run the relevant tests.

## Verification
- [ ] TypeScript build completes with zero errors
- [ ] Root cause errors are fixed (not just downstream symptoms)
- [ ] No suppressions introduced without justification (`@ts-ignore`, `as any`)
- [ ] Reproduction command now passes consistently
- [ ] Tests pass after fixes (if applicable)

## Boundaries
- MUST NOT use `@ts-ignore` to silence errors (use `@ts-expect-error` only as a justified last resort)
- MUST NOT use `as any` to force compilation
- MUST NOT fix downstream errors before root causes
- MUST NOT refactor unrelated code while fixing type errors
- SHOULD NOT skip verification after each batch of fixes

## Included assets
- Templates:
  - `./templates/triage-worksheet.md`
  - `./templates/common-fix-patterns.md`
- Examples: `./examples/` includes a sample error-to-fix mapping.