¶
Quick facts
Phase: Deliver | Version: 2.0.0 | Category: specification | License: Apache-2.0
Edge Cases¶
An edge cases document systematically catalogs the unusual, boundary, and error scenarios for a feature. While happy-path flows are typically well-specified, edge cases often get discovered in production — causing bugs, poor user experience, and support burden. Documenting edge cases upfront ensures engineering handles them intentionally and QA knows what to test.
When to Use¶
- During feature specification before engineering begins
- When preparing QA test plans
- After discovering production bugs to prevent similar issues
- When reviewing PRDs or user stories for completeness
- Before launch to ensure error states have been designed
How to Use¶
Use the /edge-cases slash command:
Or reference the skill file directly: skills/deliver-edge-cases/SKILL.md
Instructions¶
When asked to document edge cases, follow these steps:
-
Define the Feature Scope Clearly describe what feature or flow you're analyzing. Edge cases are specific to context — the same input might be valid in one feature and invalid in another.
-
Walk Through Input Validation Consider every user input: What if it's empty? Too long? Wrong format? Contains special characters? What are the minimum and maximum valid values?
-
Explore Boundary Conditions Find the edges of acceptable ranges. If a field accepts 1-100, test 0, 1, 100, and 101. Consider pagination boundaries, timeout thresholds, and rate limits.
-
Map Error States Identify what can go wrong: network failures, permission denied, resource not found, concurrent modifications, expired sessions. Document both the scenario and expected behavior.
-
Consider Concurrency Issues What if two users act simultaneously? What if the user double-clicks? What if data changes between load and save? Race conditions often cause subtle bugs.
-
Define Recovery Paths For each error, specify how users recover. What message do they see? Can they retry? Is data preserved? Good error handling turns frustration into confidence.
-
Prioritize by Likelihood and Impact Not all edge cases need the same attention. High-likelihood + high-impact cases need robust handling; rare + low-impact cases might just need graceful failure.
Output Template¶
Edge Cases: [Feature Name]¶
Feature Overview¶
[Feature description]
Related Documents: - [PRD or User Story link] - [Design specs link]
Edge Case Categories¶
Input Validation¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| [Input field] is empty | [What happens] | P1/P2/P3 | [Additional context] |
| [Input field] exceeds max length | [What happens] | P1/P2/P3 | [Max: X characters] |
| [Input field] contains special characters | [What happens] | P1/P2/P3 | [Which characters] |
| [Input field] wrong format | [What happens] | P1/P2/P3 | [Expected format] |
Boundary Conditions¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| [Value] at minimum | [What happens] | P1/P2/P3 | [Min value: X] |
| [Value] at maximum | [What happens] | P1/P2/P3 | [Max value: X] |
| [Value] below minimum | [What happens] | P1/P2/P3 | [Error handling] |
| [Value] above maximum | [What happens] | P1/P2/P3 | [Error handling] |
Error States¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| Network failure during [action] | [What happens] | P1/P2/P3 | [Retry behavior] |
| [Resource] not found | [What happens] | P1/P2/P3 | [404 handling] |
| Permission denied | [What happens] | P1/P2/P3 | [Auth flow] |
| Session expired | [What happens] | P1/P2/P3 | [Re-auth flow] |
| Server error (5xx) | [What happens] | P1/P2/P3 | [Fallback behavior] |
Concurrency¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| User double-clicks submit | [What happens] | P1/P2/P3 | [Debounce/disable] |
| Two users edit same [resource] | [What happens] | P1/P2/P3 | [Conflict resolution] |
| Data changes after page load | [What happens] | P1/P2/P3 | [Stale data handling] |
Integration Failures¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| [External service] unavailable | [What happens] | P1/P2/P3 | [Fallback/retry] |
| [External service] returns error | [What happens] | P1/P2/P3 | [Error mapping] |
| [External service] timeout | [What happens] | P1/P2/P3 | [Timeout value: Xs] |
Error Messages¶
| Error State | User Message | Additional Action |
|---|---|---|
| [Error 1] | "[Message shown to user]" | [Button/link if any] |
| [Error 2] | "[Message shown to user]" | [Button/link if any] |
| [Error 3] | "[Message shown to user]" | [Button/link if any] |
Recovery Paths¶
[Error State 1]¶
User sees: [Error message or UI state]
Recovery options: 1. [Primary recovery action] 2. [Alternative recovery action]
Data preservation: [What data is saved/lost]
[Error State 2]¶
User sees: [Error message or UI state]
Recovery options: 1. [Primary recovery action] 2. [Alternative recovery action]
Data preservation: [What data is saved/lost]
Test Scenarios¶
Must Test (P1)¶
- [Test scenario 1]
- [Test scenario 2]
- [Test scenario 3]
Should Test (P2)¶
- [Test scenario 4]
- [Test scenario 5]
Nice to Test (P3)¶
- [Test scenario 6]
- [Test scenario 7]
Example Output¶
Edge Cases: File Upload
Edge Cases: File Upload¶
Feature Overview¶
Users can upload documents (PDF, Word, images) to their workspace. Files are stored in cloud storage with metadata in our database. Maximum file size is 100MB, with a limit of 50 files per upload batch.
Related Documents: - PRD: Document Upload Feature (PRD-2026-012) - Design: Upload Flow Mockups (Figma/uploads-v2)
Edge Case Categories¶
Input Validation¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| No file selected | Submit button disabled, tooltip: "Select files to upload" | P1 | Prevent empty submissions |
| File has no extension | Reject with error: "File type could not be determined" | P2 | Security: don't guess types |
| File extension doesn't match content | Reject with error: "File appears corrupted or mislabeled" | P1 | MIME type validation |
| Filename contains special characters | Accept but sanitize: replace with underscores | P2 | Allow unicode, strip \/:<>*? |
| Filename exceeds 255 characters | Truncate to 255, preserve extension | P3 | Show truncation warning |
| Filename is empty (just extension) | Reject with error: "Please provide a filename" | P2 | e.g., ".pdf" alone |
| Duplicate filename in same folder | Append "(1)", "(2)" etc. automatically | P2 | Show rename notification |
Boundary Conditions¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| File exactly 100MB | Accept | P1 | Boundary acceptance |
| File 100MB + 1 byte | Reject: "File exceeds 100MB limit" | P1 | Clear limit enforcement |
| File is 0 bytes | Reject: "File appears to be empty" | P2 | Prevent empty file uploads |
| 50 files in batch (max) | Accept all | P1 | Batch limit boundary |
| 51 files in batch | Reject batch: "Maximum 50 files per upload" | P1 | Pre-upload validation |
| Single file with 50 already in folder | Accept (folder limits are separate) | P3 | Clarify vs batch limit |
Error States¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| Network failure during upload | Pause upload, show "Connection lost. Retry?" | P1 | Auto-retry 3x before asking |
| Network failure mid-file | Resume from last chunk when reconnected | P1 | Chunked upload recovery |
| Storage quota exceeded | Reject: "Storage full. Free up space or upgrade." | P1 | Check before upload starts |
| File locked/in use (Windows) | Reject: "File is in use. Close it and try again." | P2 | Clear guidance |
| Upload session expires (>1 hour) | Restart upload with warning | P2 | Token refresh failed |
| File deleted locally during upload | Skip file, continue others: "1 file no longer available" | P2 | Non-blocking failure |
| Server error (5xx) | Show "Upload failed. Please try again." + retry button | P1 | Generic fallback |
| Malware detected by scanner | Reject file, quarantine, notify admin | P1 | Security critical |
Concurrency¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| User double-clicks upload | Ignore second click (button disabled during upload) | P1 | Prevent duplicate uploads |
| User navigates away during upload | Warning: "Upload in progress. Leave anyway?" | P1 | Confirmation dialog |
| User starts second upload batch | Queue second batch, show queue UI | P2 | Or reject with "upload in progress" |
| Same file uploaded simultaneously by 2 users | Both succeed with unique versions | P3 | Conflict resolution via versioning |
| User refreshes page during upload | Upload cancelled, show restart option on return | P2 | Cannot persist upload state |
Integration Failures¶
| Scenario | Expected Behavior | Priority | Notes |
|---|---|---|---|
| Cloud storage unavailable | Retry 3x, then "Upload temporarily unavailable" | P1 | 30-second timeout |
| Virus scanner timeout | Proceed with upload, flag for async scan | P2 | Don't block on slow scans |
| Virus scanner unavailable | Proceed with upload, flag for later scan | P2 | Queue for retry |
| Metadata service failure | Upload to storage, queue metadata write | P2 | Eventually consistent |
| Thumbnail generation failure | Upload succeeds, show generic icon | P3 | Non-critical failure |
Error Messages¶
| Error State | User Message | Additional Action |
|---|---|---|
| File too large | "This file is too large. Maximum size is 100MB." | "Compress file" link to help |
| Unsupported type | "This file type isn't supported. Try PDF, Word, or images." | List of supported types |
| Network failure | "Connection lost. Check your internet and try again." | [Retry] button |
| Storage full | "You've run out of storage space." | [Upgrade] or [Manage storage] |
| Permission denied | "You don't have permission to upload here." | [Request access] |
| Upload failed (generic) | "Something went wrong. Please try again." | [Retry] + [Contact support] |
| Malware detected | "This file was blocked for security reasons." | [Learn more] |
Recovery Paths¶
Network Failure During Upload¶
User sees: Progress bar pauses, toast notification: "Connection lost. Retrying..."
Recovery options: 1. Automatic retry (3 attempts, 5-second intervals) 2. Manual retry button after auto-retry exhausted 3. Cancel upload and start over
Data preservation: Completed file chunks preserved. Upload resumes from last successful chunk.
Storage Quota Exceeded¶
User sees: Modal: "You've run out of storage space. You're using 10GB of 10GB."
Recovery options: 1. Click "Manage storage" to delete files 2. Click "Upgrade plan" for more space 3. Cancel upload, files not uploaded
Data preservation: No partial upload — check happens before transfer starts.
Session Expired During Long Upload¶
User sees: Toast: "Your session expired. Please sign in to continue."
Recovery options: 1. Sign in via modal (doesn't lose page state) 2. If sign-in succeeds, upload auto-resumes 3. If sign-in fails, upload cancelled
Data preservation: Upload progress preserved during re-auth attempt.
Test Scenarios¶
Must Test (P1)¶
- Upload file exactly 100MB — should succeed
- Upload file 100MB + 1KB — should fail with size error
- Upload 50 files at once — should succeed
- Upload 51 files at once — should fail with batch limit error
- Disconnect network mid-upload — should pause and recover
- Upload .exe disguised as .pdf — should be rejected (MIME check)
- Double-click upload button — should only upload once
Should Test (P2)¶
- Upload file with unicode filename — should sanitize
- Upload file with 300-character name — should truncate
- Upload 0-byte file — should fail
- Upload duplicate filename — should auto-rename
- Navigate away during upload — should show warning
- Storage 99% full, upload 2% of quota — should fail
Nice to Test (P3)¶
- Upload when thumbnail service down — should succeed with generic icon
- Two users upload same file simultaneously — both should succeed
- Upload file with only extension (.pdf) — should fail
Real-World Examples¶
See this skill applied to three different product contexts:
Storevine (B2B): Storevine B2B ecommerce platform — Campaigns campaign send flow edge cases
Prompt:
/edge-cases
Feature: Campaigns — campaign creation and send flow
Sprint: Q2 2026 Campaigns build (GA Apr 28, 2026)
Key edge cases I want to cover:
- Input validation: subject line, email body, audience size, physical
sender address (CAN-SPAM requirement)
- Boundary conditions: free tier send volume limit, min/max audience size
- Error states: network failure during send, SendGrid API errors
- Concurrency: double-click send, merchant edits in two browser tabs
- Integration failures: SendGrid unavailable, attribution webhook down
Related docs:
- User story US-CAM-001 (guided first-campaign flow)
- Spike summary: SendGrid attribution webhook confirmed
- Edge cases will be used for QA test plan and engineering handoff
Need: full edge cases document with error messages, recovery paths, and
QA test scenarios (P1/P2/P3).
Output:
Edge Cases: Campaigns Campaign Send Flow¶
Brainshelf (Consumer): Brainshelf consumer PKM app — Resurface digest edge cases and error states
Prompt:
/edge-cases
resurface edge cases for sprint 8. need to cover:
- what happens when the user's library is too small
- what happens when all items have been resurfaced recently
- timezone weirdness (DST, user changes timezone, half-hour offsets)
- text extraction failures
- resend api outages
- user clicks a link to a dead URL
- email bounces
- concurrent opt-in/unsubscribe race conditions
alex wants this documented so QA can build the test plan from it.
Output:
Edge Cases: Resurface Digest¶
Workbench (Enterprise): Workbench enterprise collaboration platform - Blueprints edge-case analysis for approval workflows and co-editing
Prompt:
/edge-cases
I need a comprehensive edge-case analysis for Blueprints v1 covering the three highest-risk areas: required-section enforcement boundaries, approval-gate state transitions, and real-time co-editing conflicts.
**Context:**
- Required sections use a content-presence check (non-whitespace); submit is disabled until all required sections have content
- Approval gates support sequential and parallel chains; state stored in relational DB, not in the Yjs document
- Co-editing uses Yjs CRDTs with sub-document-level sync; offline edits cache locally and merge on reconnect
- 80 closed-beta accounts [fictional], target ~20 concurrent editors per Blueprint [fictional]
**What I need:**
- Edge cases organized by category
- Error messages for each failure state
- Recovery paths so QA and engineering know the expected behavior
- Prioritized test scenarios (P1 must-test, P2 should-test, P3 nice-to-test)
Please be thorough -- Karen's team will use this directly for test planning.
Output:
Edge Cases: Workbench Blueprints v1¶
Quality Checklist¶
Before finalizing, verify:
- All user inputs have validation edge cases documented
- Boundary conditions are explicitly listed
- Network/system failure scenarios are covered
- Each error state has a defined user-facing message
- Recovery paths are specified (not just error detection)
- Edge cases are prioritized by likelihood and impact
Output Format¶
Use the template in references/TEMPLATE.md to structure the output.