debug-phase

<quick_start> Debug errors systematically:

1. Reproduce error consistently (100% reliable reproduction)
2. Classify by type (syntax/runtime/logic/integration/performance) and severity (critical/high/medium/low)
3. Isolate root cause using binary search, logging, breakpoints, or 5 Whys
4. Implement fix with failing test first (TDD)
5. Add regression tests to prevent recurrence
6. Document in error-log.md with ERR-XXXX ID

Key principle: Fix root causes, not symptoms. Use 5 Whys to drill down. </quick_start>

Check error-log.md for similar historical errors before starting.

Check error-log.md for past occurrences:

# Search by error message
grep -i "connection timeout" error-log.md

# Search by component
grep "Component: StudentProgressService" error-log.md

# Search by error type
grep "Type: Integration" error-log.md

If similar error found:

• Review previous fix (workaround or root cause?)
• Check if error recurred (>2 occurrences = need permanent fix)
• Note patterns (same component, same conditions, timing)

If recurring error: Prioritize permanent fix over workaround.

Create minimal reproduction:

1. Gather context: error message, stack trace, timestamp, user actions, environment
2. Create minimal test case that triggers error 100% of time
3. If intermittent: identify conditions (timing, data state, race conditions)

Example reproduction:

# API error
curl -X POST http://localhost:3000/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'

# Frontend error
# 1. Navigate to /dashboard
# 2. Click "Load Data" button
# 3. Error appears in console

Validation: Can trigger error reliably before proceeding.

By type:

• Syntax: Code doesn't compile/parse (typos, missing brackets, linting errors)
• Runtime: Code runs but crashes (null pointer, type error, uncaught exception)
• Logic: Code runs but wrong result (calculation error, wrong branch taken)
• Integration: External dependency fails (API timeout, database connection, service unavailable)
• Performance: Code works but too slow (timeout, memory leak, N+1 queries)

By severity:

• Critical: Data loss, security breach, total system failure
• High: Feature broken, blocks users from core functionality
• Medium: Feature degraded, workaround exists
• Low: Minor UX issue, cosmetic, no functional impact

Example classification:

Type: Integration (API call to external service fails)
Severity: High (dashboard doesn't load, blocks teachers)
Component: StudentProgressService.fetchExternalData()
Frequency: 30% of requests (intermittent)

See references/error-classification.md for detailed matrix.

Use systematic techniques:

Binary search (for large codebases):

• Add logging at midpoint of suspected code
• If error before midpoint → investigate first half
• If error after midpoint → investigate second half
• Repeat until narrowed to specific function

Increase logging:

# Add debug logs around suspected area
logger.debug(f"Before API call: student_id={student_id}, params={params}")
response = api.fetch_data(student_id)
logger.debug(f"After API call: status={response.status}, data_len={len(response.data)}")

Use breakpoints (interactive debugging):