---
title: "Edge Cases"
description: "Documents edge cases, error states, boundary conditions, and recovery paths for a feature. Use during specification to ensure comprehensive coverage, or during QA planning to identify test scenarios."
generated: true
source: scripts/generate-skill-pages.py
tags:
  - Deliver
  - specification
---

:::note[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:

1. **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.

2. **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?

3. **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.

4. **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.

5. **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.

6. **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.

7. **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

<!-- Brief description of the feature being analyzed -->

[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

<!-- User-facing copy for each error state -->

| 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

<!-- How users recover from each error -->

### [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

<!-- QA checklist derived from edge cases -->

### 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

<details>
<summary>Edge Cases: File Upload</summary>

# 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

</details>

## Real-World Examples

See this skill applied to three different product contexts:

<details>
<summary>Storevine (B2B): Storevine B2B ecommerce platform . Campaigns campaign send flow edge cases</summary>

**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

</details>

<details>
<summary>Brainshelf (Consumer): Brainshelf consumer PKM app . Resurface digest edge cases and error states</summary>

**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

</details>

<details>
<summary>Workbench (Enterprise): Workbench enterprise collaboration platform - Blueprints edge-case analysis for approval workflows and co-editing</summary>

**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

</details>

## 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.
