# Debugging Instructions - Fiddy

## Scope and authority
- This file is required for bugfix work.
- `PROJECT_INSTRUCTIONS.md` remains the source of truth for global project rules.
- For debugging tasks, ship the smallest safe fix that resolves the verified issue.

## Required bugfix workflow
1. Reproduce:
   - Capture exact route/page, inputs, actor role, and expected vs actual behavior.
   - Record a concrete repro sequence before changing code.
2. Localize:
   - Identify the failing boundary (route/controller/model/service/client wrapper/hook/ui).
   - Confirm whether failure is validation, authorization, data, or rendering.
3. Fix minimally:
   - Modify only the layers needed to resolve the bug.
   - Do not introduce parallel mechanisms for the same state flow.
4. Verify:
   - Re-run repro.
   - Run lint/tests for touched areas.
   - Confirm no regression against contracts in `PROJECT_INSTRUCTIONS.md`.

## Guardrails while debugging
- External DB only:
  - Use `DATABASE_URL`.
  - Never add a DB container for a fix.
- No background jobs:
  - Do not add cron, workers, or polling daemons.
- Security:
  - Never log secrets, receipt bytes, or full invite codes.
  - Invite logs/audit may include only last4.
- Authorization:
  - Enforce RBAC server-side; client checks are UX only.

## Contract-specific debug checks
- Auth:
  - Sessions must remain DB-backed and cookie-based (HttpOnly).
- Receipts:
  - List endpoints must never include receipt bytes.
  - Byte retrieval must be through dedicated endpoint only.
- Request IDs/audit:
  - Ensure `request_id` appears in responses and audit trail for affected paths.

## Evidence to include with every bugfix
- Root cause summary (one short paragraph).
- Changed files list with rationale.
- Verification steps performed and outcome.
- Any residual risk, fallback, or operator action.