troubleshooting

Troubleshooting

You MUST review the troubleshooting guideline when diagnosing test failures, build errors, or performance issues.

When to Use This Skill

• Debugging unit test failures or timing issues
• Investigating visual regression test differences
• Troubleshooting Lighthouse performance scores
• Resolving build failures or Wireit cache issues
• Fixing Git LFS problems with visual baselines
• Diagnosing CI/CD pipeline failures
• Resolving development environment setup issues
• Investigating performance regressions in tests or builds

Must Read File

Read the troubleshooting guide to get critical context for troubleshooting guidance.

Diagnostic Triage Workflow

1. Identify the symptom category:

   • Test failure:unit, axe, visual, SSR, or lighthouse?
   • Build failure:Wireit cache, dependency resolution, TypeScript, or circular imports?
   • Environment issue:Node version, pnpm version, Git LFS, or port conflict?
   • Performance regression:slow tests, slow builds, or large bundles?

2. Run the relevant diagnostic commands:

   • Test failures: pnpm run test -- src/<component>/<component>.test.ts (isolate the failing test)
   • Build failures: pnpm run ci:reset then pnpm run build (clear caches first)
   • Environment: node --version && pnpm --version && git lfs env (verify toolchain)

3. Check the matching section in the troubleshooting guide for the specific symptom/solution pair.

4. If the issue persists, compare against a working reference component (badge, button, or card) to spot structural differences.

References

• Troubleshooting Guide - Common issues and solutions
• Testing Guidelines - Test patterns
• Unit Testing - Unit test details
• Visual Testing - Visual regression details
• Lighthouse Testing - Performance testing
• Build System - Wireit troubleshooting