TAC Express — Systematic Debugging

Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Symptom fixes are failure. Random fixes waste time and create new bugs.

---

The Four Phases

You MUST complete each phase before proceeding to the next.

Phase 1: Root Cause Investigation

Before touching any code:

1. Read the error completely

   • Full stack trace, not just the last line
   • Note file paths, line numbers, error codes
   • Check for nested errors (cause: property)

2. Reproduce consistently

   • Can you trigger it every time?
   • Is it browser-specific? Node version? OS?
   • What are the exact steps?

3. Check recent changes

   • git log --oneline -20 — what changed?
   • git diff HEAD~3..HEAD — what's different?
   • New package install? Config change?

4. For multi-package errors (common in this monorepo):

   # Identify which package boundary fails:
   pnpm --filter @workspace/ui typecheck
   pnpm --filter @workspace/services typecheck
   pnpm --filter web typecheck
   pnpm --filter dashboard typecheck
   

5. Trace data flow backward

   • Where does the bad value originate?
   • UI → Service → Database — which layer breaks?
   • Add console.error at each boundary if unclear

Phase 2: Pattern Analysis

1. Find working code that does something similar in this codebase
2. Compare working vs. broken — list every difference, however small
3. Check DESIGN_SYSTEM.md / AGENTS.md § 4 — is a rule being violated?
4. Check if a forbidden package was accidentally used

Phase 3: Hypothesis & Test

1. State ONE specific hypothesis: "I think X fails because Y"
2. Make the SMALLEST change to test it
3. Verify result
4. If wrong: form NEW hypothesis — do NOT stack fixes

Three strikes rule: If 3+ different fixes have failed, STOP. The architecture may be wrong. Discuss before continuing.

Phase 4: Implement the Fix

1. Write a failing test that captures the bug
2. Implement the minimal fix
3. Verify the test now passes
4. Verify no other tests broke
5. Commit with: fix(scope): describe root cause and fix

---

TAC Express-Specific Debug Checklist

Build Errors

# Run in order — each isolates a different layer:
pnpm typecheck                    # TypeScript errors
pnpm lint --max-warnings 0       # ESLint violations  
pnpm --filter @workspace/ui build # UI package builds?
pnpm build                        # Full monorepo build

Common TAC Express Pitfalls

Symptom	Likely Cause	Check
Cannot find module '@workspace/ui'	Build order issue	Run pnpm build --filter @workspace/ui first
CSS token not applying	Token not in globals.css	Check token name matches exactly
Supabase error in component	Direct DB call in component	Move to packages/services
lucide-react import error	Forbidden package	Replace with @remixicon/react
Hydration mismatch	useEffect missing deps	Check SSR/CSR boundary
Type error in service	Missing return type	Add explicit return type annotation

ESLint Violations Debug

# See all violations with context:
pnpm lint --max-warnings 0 2>&1 | head -100

# Fix auto-fixable:
pnpm lint --fix

# Check specific file:
pnpm dlx eslint packages/ui/src/components/MyComponent.tsx

Turbopack / Next.js Issues

# Clear all caches:
Remove-Item -Recurse -Force apps/web/.next
Remove-Item -Recurse -Force apps/dashboard/.next
Remove-Item -Recurse -Force node_modules/.cache
pnpm dev

---

Red Flags — STOP and Re-investigate

If you catch yourself:

• "Let me just try changing this and see..."
• Adding multiple fixes at once
• Skipping the test step
• "It's probably the same issue as before..."
• Proposing solutions before reading the error trace
• Attempting Fix #4 without discussing architecture

All of these mean: STOP. Return to Phase 1.

---

Debug Notes Format

When documenting a resolved bug:

## Bug: [short description]
Date: YYYY-MM-DD
Ticket: TAC-XXX

### Root Cause
[Exact explanation of what caused it]

### Evidence
[Stack trace, error message, or data that confirmed root cause]

### Fix
[What was changed and why it works]

### Prevention
[Test added, rule updated, or pattern to follow going forward]