template-repo/docs/edge-cases.md

Edge Case Catalogue

Capture every non-happy-path scenario that has bitten you in past projects. Use these prompts when planning features, writing tests, and updating documentation.

Authentication & Authorization

• What happens when the identity provider is unavailable or rate-limited?
• Can users authenticate with multiple providers? How do you reconcile identities?
• Do access tokens expire mid-session? Plan silent refresh and forced logout flows.
• Are admin-only routes guarded on the server, not just the client?
• How do you roll keys or secrets without booting everyone?

Feature Flags & Configuration

• Can new features be disabled quickly without redeploying?
• Are default values safe when the config service is unreachable?
• What is logged when a flag evaluation fails?

Data & Persistence

• Are migrations idempotent? Can you roll them back?
• Do background jobs tolerate partial failure or duplicate delivery?
• What size assumptions exist for JSON payloads, binary blobs, or text fields?
• How do you seed development data without leaking production secrets?

Scheduling & Calendars

• Do you store timestamps in UTC and render them with the user's offset?
• How do you handle daylight saving transitions and leap seconds?
• Can overlapping events be created? If not, validate and surface clear errors.
• What is the source of truth when multiple calendars sync into one timeline?

File & Asset Management

• Maximum file size? Enforce both client and server-side.
• Are uploads scanned, transcoded, or resized? Where is the queue?
• How do you serve private files? Signed URLs, download proxies, expiring tokens?
• What is the retention policy and deletion workflow?

External Services

• Plan for timeouts, retries, and rate limits on each integration.
• If a vendor returns partial data, does your UI still render something helpful?
• Document SLAs and fallbacks in docs/stack-decisions.md.

Observability & Recovery

• Which metrics, logs, and traces are mandatory before launch?
• Do alerts route to a real person with enough context to act?
• After an incident, what automated reports or scripts help recreate the scenario?

Compliance & Privacy

• How do you handle data export, erasure, and consent?
• What environments carry production data? Are they encrypted at rest?
• Which audit logs must be preserved, and where?

When a new surprise occurs, write the story here, then open a PR to harden the template so the next project benefits immediately.