diagnosing-type-errors

Project configuration: @tsconfig.json @package.json </context>

1. Run Type Check

Execute type checking and collect all errors for the target file:

pnpm type-check 2>&1 | grep "target-file"

Replace target-file with the actual file path from the user's request.

If no errors found, report success and exit.

2. Classify Errors

Group errors by category:

• •Type mismatches (assignability errors)
• •Missing properties (required fields)
• •Null/undefined safety violations
• •Generic constraint violations
• •Function signature mismatches
• •Import/export type errors
• •Configuration issues (module resolution, lib types)

Identify error severity and impact:

• •Critical: Prevents compilation, blocks functionality
• •High: Type unsoundness, runtime risk
• •Medium: Poor type design, maintenance burden
• •Low: Minor inconsistencies, style issues

Detect patterns across multiple errors:

• •Common root cause affecting multiple locations
• •Cascading errors from single source
• •Repeated anti-patterns

3. Root Cause Analysis

For each error, trace to its source:

Read the target file specified by the user

Identify error origin:

• •Incorrect type annotations (wrong type specified)
• •Missing type definitions (implicit any)
• •Third-party library types (DefinitelyTyped issues)
• •Configuration issues (tsconfig strictness)
• •Type narrowing failures (guard logic errors)
• •Generic inference failures (constraints needed)

Explain why each error occurs:

• •What TypeScript rule is being violated
• •Why the types are incompatible
• •What the type system expected vs. received
• •How the error propagates through code

4. Provide Recommendations

For each error, suggest specific fixes:

Immediate fixes:

• •Exact code changes needed (line numbers, syntax)
• •Type annotations to add/modify
• •Type guards to implement
• •Assertions to safely apply (when justified)

Type refactoring opportunities:

• •Overly broad types that need narrowing
• •Union types that need discrimination
• •Generic types that need constraints
• •Interfaces that need extension

Type extraction candidates:

• •Inline types used multiple times
• •Complex type expressions needing names
• •Shared type patterns across files
• •Utility types that could simplify code

Type safety improvements:

• •Replace any with unknown + guards
• •Add strict null checks where missing
• •Strengthen generic constraints
• •Use branded types for validation

Communication Requirements:

• •Use clear, educational explanations
• •Reference TypeScript documentation for complex issues
• •Provide actionable, specific recommendations
• •Prioritize fixes by severity and impact
• •Group related errors together

Code Quality Requirements:

• •MUST maintain existing code structure
• •MUST follow project naming conventions
• •NEVER introduce breaking changes
• •Consider backward compatibility </constraints>

Error Summary

• •Total errors: {count}
• •Categories: {list with counts}
• •Severity: {critical/high/medium/low breakdown}

Error Analysis

For each error:

Error {n}: {category} - {severity}

Location: {file}:{line}:{column}

Error message:

{TypeScript error message}

Root cause: {Explanation of why this error occurs}

Affected code:

{Code snippet showing the error}

Recommended fix:

{Exact code change needed}

Explanation: {Why this fix resolves the error}

Refactoring Opportunities

• •{List of type improvements that could be made}
• •{Extraction candidates for reusable types}
• •{Type safety enhancements beyond error fixes}

Next Steps

1. •{Prioritized action items}
2. •{Suggested order of fixes}
3. •{Long-term type improvements to consider}