Debug Investigate Skill

debug_investigate.md

name	debug-investigate
description	Use when investigating bugs, diagnosing failures, debugging runtime issues, or when a fix attempt hasn't worked. Provides structured debugging workflow: instrument first, gather evidence, never commit speculative fixes, mobile bug handling.

Debugging & Investigation Workflow

Step 1: Instrument Before Investigating

If structured logging or error handling is missing from the code under investigation, add it FIRST. Treat missing instrumentation as a bug to fix before diagnosing the actual issue.

// Add before the suspected failure point:
logger.info({ operation: 'functionName', input: relevantData }, 'Starting operation');
try {
  // ... suspected code ...
  logger.info({ operation: 'functionName', result }, 'Operation succeeded');
} catch (err) {
  logger.error({ operation: 'functionName', err: err.message, input: relevantData }, 'Operation failed');
  throw err;
}

Step 2: Gather Evidence

Do NOT commit speculative fixes. Instead:

1. Add diagnostic logging at suspected failure points
2. Run the failing scenario
3. Read the logs/output
4. Identify the actual root cause from evidence

If a fix doesn't work on the first attempt, STOP guessing. Add more diagnostics instead.

Step 3: Fix With Evidence

Only commit a fix when you have:

• Clear evidence of what was wrong (log output, error message, stack trace)
• Confidence the fix addresses the root cause (not just a symptom)
• Verified the fix works (ran the scenario again)

Step 4: Commit Immediately When Fixed

Once uncommitted changes resolve the issue:

1. Run git add and git commit immediately
2. Do NOT continue investigating root causes or alternatives
3. Ask the user if they want deeper analysis after committing

Edge Function Debugging

For 4xx/5xx errors in edge functions:

1. Check structured logs first (console.error output in Supabase dashboard or local serve)
2. Verify env vars are loaded (check --env-file flag or supabase secrets list)
3. If logs insufficient, request the Network tab payload from the user

Mobile Bug Debugging

• Playwright/emulator taps bypass real hit-testing — don't trust emulation for touch bugs
• Secure-context checks differ — features requiring HTTPS may work in emulator but fail on device
• iOS Safari auto-zoom — triggered by inputs with font-size < 16px. Fix: use text-base
• Mobile bugs require runtime evidence — test on a real device or ask user for screenshots/recordings

Common Patterns

RLS Silent Failures

The Supabase JS client returns { error: null } when RLS blocks DELETE/UPDATE — it affects 0 rows silently. Verify with:

const { count, error } = await supabase.from('table').delete({ count: 'exact' }).eq('id', id);
if (!count) console.error('RLS may have blocked this operation');

Edge Function Auth Failures

If getting 401 on a function that should work:

1. Check if using new key format (sb_secret_...) vs old JWT (eyJhbGci...)
2. Verify the env var name matches what the function reads (SB_SECRET_API_KEY vs SUPABASE_SERVICE_ROLE_KEY)
3. Check if the function expects apikey header vs Authorization: Bearer header

React State Issues

If UI isn't updating after a successful operation:

1. Check if the service function returns the updated data
2. Verify the component re-renders (add a console.log in the render body)
3. Check if there's a stale closure (common with useEffect dependencies)

Step 5: Post-Fix Verification

After committing the fix, co-invoke related skills:

• If the fix touched visual presentation, layout, or CSS → invoke /ux-review to verify UX compliance
• If tests exist for the affected component → invoke /frontend-test to run them