# Support Triage Playbook

This playbook helps demo operators and maintainers respond quickly during public crowdfunding updates, stakeholder calls, and QA sessions.

## Severity levels

| Severity | Definition | Response target |
| --- | --- | --- |
| S1 | Demo cannot start, API is down, or web app cannot load | Immediate response during a scheduled demo |
| S2 | Core gameplay loop is blocked for most users | Same day |
| S3 | One flow has a workaround, such as one trivia question failing | Next planned patch |
| S4 | Copy, layout, or documentation issue with no gameplay impact | Batch into release notes |

## First response checklist

1. Record browser, device, viewport, and operating system.
2. Capture the failing action: collect, trivia, prediction, badge, challenge, or leaderboard.
3. Save the API response status and message from the browser network panel.
4. Confirm whether the issue reproduces after refresh.
5. Confirm whether the issue reproduces in a clean browser profile.
6. Run static preflight:

   ```bash
   node scripts/qa/release-preflight.mjs
   ```

7. If the API is running locally, run smoke checks:

   ```bash
   API_BASE_URL=http://localhost:4000 node scripts/qa/http-smoke.mjs
   ```

## Common issues

| Symptom | Likely cause | Triage action |
| --- | --- | --- |
| App shows a loading state forever | API not running or wrong API base URL | Check `.env`, `VITE_API_BASE_URL`, and API health URL. |
| Collect button returns an error | Duplicate item or unknown item id | Verify the UI shows the friendly duplicate/invalid item message. |
| Trivia answer does not change score | Question already answered, answer is invalid, or API response was rejected | Inspect response body and retest with a fresh demo user. |
| Prediction form is disabled | Match is closed, missing selection, or loading state is active | Confirm seeded match status and UI validation text. |
| Badge appears twice | Gamification idempotency regression | Run API integration tests and inspect badge award rules. |
| Challenge does not complete after action | Challenge requirement mismatch | Confirm the relevant collection/trivia/prediction count in passport response. |
| Leaderboard does not move | Points were not awarded or leaderboard cache is stale | Refresh passport, then leaderboard, and compare points. |
| Mobile layout clips action buttons | Responsive styling regression | Test at 360px, 390px, 768px, and 1024px widths. |
| Keyboard focus disappears | Focus style or disabled state regression | Tab through cards, forms, and leaderboard controls. |
| CORS error in browser console | Web origin not allowed by API | Set API `CORS_ORIGIN` to the web app origin and restart API. |

## Demo recovery steps

### Local npm demo

```bash
npm install
npm run dev
```

If root `dev` is unavailable in a branch, run workspaces directly:

```bash
npm --workspace apps/api run dev
npm --workspace apps/web run dev
```

### Docker demo

```bash
docker compose -f docker-compose.demo.yml up --build
```

If a cached layer is suspected:

```bash
docker compose -f docker-compose.demo.yml build --no-cache
docker compose -f docker-compose.demo.yml up
```

### Reset demo state

The MVP is designed for demo data. If state becomes confusing during a presentation:

1. Stop the API process.
2. Restart the API process.
3. Refresh the web app.
4. Use the scripted user journey in `docs/demo-script.md`.

If a future persistent database is added, provide a seeded reset command and restrict it to non-production environments.

## Browser QA matrix

Run the primary path on:

| Browser | Desktop | Mobile |
| --- | --- | --- |
| Chrome | Required | Required via device emulation |
| Safari | Required on macOS | Required on iOS when available |
| Firefox | Recommended | Optional for public demo |
| Edge | Recommended | Optional |

Primary path:

1. Load passport.
2. Collect one team or stadium.
3. Answer one trivia question correctly.
4. Submit one prediction.
5. Observe badge or challenge unlock.
6. Open leaderboard and confirm movement.

## Escalation package

When escalating to an engineer, include:

- Exact route or UI action
- Request method and URL
- Response status and response body
- Screenshot or screen recording
- Browser console output
- Demo user id
- Whether the issue reproduces in Docker Compose
- Whether `release-preflight`, API tests, and e2e tests pass

## Demo-day operating rhythm

Before the public update:

1. Pull latest main branch.
2. Run `npm install`.
3. Run `node scripts/qa/release-preflight.mjs`.
4. Run unit/integration tests.
5. Run e2e tests.
6. Start the demo.
7. Walk through `docs/demo-script.md` once without recording.
8. Keep this triage guide open during the live session.