Resolve Typescript Build Errors

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.