costco-grocery-list/DEBUGGING_INSTRUCTIONS.md

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.