Debug Issue Command

Command

/debug

Description

Guides a systematic debugging process using the scientific method. Instead of trial-and-error, this command enforces a disciplined approach: observe the symptoms, form hypotheses, test each one, implement a targeted fix, and verify the resolution.

Behavior

Arguments

• $ARGUMENTS -- Error description, stack trace, or bug report

Debugging Protocol

Step 1: Observe

Gather all available evidence before forming any conclusions.

Copy
## Observations
- **Error**: TypeError: Cannot read property 'email' of undefined
- **Location**: src/services/userService.ts:42
- **When**: After login with Google OAuth
- **Frequency**: Every time (not intermittent)
- **Recent changes**: git log --oneline -5
  - abc1234 Added Google OAuth provider
  - def5678 Refactored user model

Step 2: Hypothesize

List possible causes ranked by probability.

Copy
## Hypotheses
1. **Google OAuth response has different shape** (80% likely)
   Evidence: Error started after adding Google OAuth
   Test: Log the OAuth callback response

2. **User model refactor broke the mapper** (15% likely)
   Evidence: User model was recently changed
   Test: Check if email is in the new model shape

3. **Race condition in async user creation** (5% likely)
   Evidence: None yet
   Test: Add logging around user creation flow

Step 3: Test Each Hypothesis

For each hypothesis, gather evidence to confirm or eliminate it.

Copy
# Hypothesis 1: Check OAuth response shape
grep -n "oauth.*callback\|google.*response" src/services/authService.ts

# Hypothesis 2: Check user model
grep -n "email" src/models/user.ts

# Add targeted logging if needed (will remove later)

Step 4: Root Cause Identification

Copy
## Root Cause: Confirmed Hypothesis 1

The Google OAuth response returns `email_address` but the mapper
expects `email`. The GitHub OAuth response uses `email`, which is
why it worked before.

File: src/services/authService.ts:87
Line: `const email = oauthResponse.email;`
Should be: `const email = oauthResponse.email || oauthResponse.email_address;`

Step 5: Fix

Implement the minimal, targeted fix.

Step 6: Verify

1. Reproduce the original bug scenario
2. Confirm the fix resolves it
3. Run the full test suite for regressions
4. Remove any debug logging added during investigation

Output Format

Copy
## Debug Report

**Issue**: Google OAuth login throws TypeError
**Root Cause**: OAuth response field name mismatch (`email_address` vs `email`)
**Fix**: Normalize OAuth response fields in authService.ts:87
**Verification**: Manual test + 3 new unit tests
**Time to Resolution**: 12 minutes

### Prevention
- Add TypeScript interface for OAuth response
- Add integration test for each OAuth provider

Examples

Copy
# Debug with error message
/debug TypeError: Cannot read property 'email' of undefined at userService.ts:42

# Debug a failing test
/debug test "should create user" fails with timeout

# Debug unexpected behavior
/debug API returns 200 but response body is empty