debug-prod

Debug Production Issue

Systematically investigate production issues across the tour-expense-tracker multi-portal architecture. This skill should be dispatched as a subagent to avoid polluting the main conversation context.

6-Step Investigation Process

Step 1: Identify the Portal from the Symptom

Determine which portal the issue originates from based on authentication patterns and entry points:

Portal	Auth mechanism	Key auth file	Typical symptoms
Guide	JWT token	src/lib/guide-auth.ts	Guide login fails, tour data not loading, expense submission errors
Driver	JWT token	src/lib/driver-auth.ts	Driver login fails, trip assignments not visible, location updates failing
Partner	Server actions	src/app/actions/partner-admin-actions.ts	Partner dashboard errors, hotel/activity management issues
Traveler	PIN code	src/lib/traveler-auth.ts	PIN login fails, itinerary not loading, booking status wrong
Dashboard	NextAuth	src/lib/auth.ts	Admin login fails, reports not generating, user management errors
Cron jobs	Cron guard	src/lib/cron-guard.ts	Scheduled tasks not running, stale data, missing notifications

Step 2: Map the Request Path

Trace the full request lifecycle:

1. URL: What endpoint was hit? (/api/... or which page route)
2. Route handler: Find the matching route.ts in src/app/api/
3. Server action: If triggered from a form/button, find the action in src/app/actions/
4. DB query: Identify the Prisma call and its filters (especially organizationId)
5. Response: What does the handler return on success vs. failure?

Step 3: Check the Auth Flow

Verify the authentication chain:

• Is the correct auth function being called for this portal?
• Are required environment variables set? (JWT_SECRET, NEXTAUTH_SECRET, CRON_SECRET, etc.)
• Is middleware intercepting the route correctly? Check src/middleware.ts
• For JWT portals: is the token being extracted from the right header/cookie?
• For NextAuth: is the session being properly retrieved?

Step 4: Inspect the Code for Common Bugs

Look for these frequent issues in the affected files:

• Null checks: Is the code handling null/undefined returns from Prisma queries?
• Wrong model names: Is the Prisma model name correct? (e.g., prisma.expense vs prisma.expenses)
• Missing await: Are async operations properly awaited?
• organizationId scoping: Is the query filtering by organizationId? Missing scope = data leak or empty results.
• Type mismatches: Is a string ID being compared to a number, or vice versa?
• Import errors: Are server-only imports leaking into client components?

Step 5: Check Recent Changes

Review git history on the affected files:

git log -10 --oneline -- <affected-file>
git diff HEAD~5 -- <affected-file>

Identify if a recent commit introduced the regression.

Step 6: Produce Structured Diagnosis

Output your findings in this format:

## Production Issue Diagnosis

**Portal:** Guide
**Symptom:** 500 error on /api/guide/expenses
**Root cause:** Missing `await` on `prisma.expense.findMany()` at `src/app/api/guide/expenses/route.ts:34`

### Request trace
1. GET /api/guide/expenses
2. → src/app/api/guide/expenses/route.ts (GET handler)
3. → verifyGuideToken() from src/lib/guide-auth.ts ✓
4. → prisma.expense.findMany({ where: { organizationId, guideId } })
5. → ✗ Returns Promise instead of data (missing await)

### Affected file(s)
- `src/app/api/guide/expenses/route.ts:34` — missing `await`

### Suggested fix
Add `await` to the Prisma query on line 34:
```ts
const expenses = await prisma.expense.findMany({...})

Risk assessment

• Impact: All guide expense views return empty/error
• Scope: Guide portal only
• Data safety: No data corruption risk — read-only query

## Tips

- Always check the Prisma schema (`prisma/schema.prisma`) to verify model names and relations.
- If the error is a 500 with no useful message, the bug is likely an unhandled exception — look for missing null checks or unvalidated input.
- For intermittent failures, check if the issue is related to expired tokens, rate limits, or database connection pooling.
- Multi-tenancy bugs (missing `organizationId`) often manifest as "no data found" rather than errors.