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.