49 lines
1.8 KiB
Markdown
49 lines
1.8 KiB
Markdown
# 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.
|