Edge Cases

Quick facts

Phase: Deliver | Version: 2.0.0 | Category: specification | License: Apache-2.0

Try it: /edge-cases "Your context here"

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:

/edge-cases "Your context here"

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:

[Primary recovery action]
[Alternative recovery action]

Data preservation: [What data is saved/lost]

[Error State 2]

User sees: [Error message or UI state]

Recovery options:

[Primary recovery action]
[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

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:

Automatic retry (3 attempts, 5-second intervals)
Manual retry button after auto-retry exhausted
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:

Click “Manage storage” to delete files
Click “Upgrade plan” for more space
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:

Sign in via modal (doesn’t lose page state)
If sign-in succeeds, upload auto-resumes
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.