Deliver Edge Cases

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | 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

• When you need to enumerate failure modes, race conditions, timeouts, and boundary or limit scenarios - everything that can go wrong - and define a recovery path for each
• 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

When NOT to Use

• You need story-scoped Given/When/Then checks for handoff -> use deliver-acceptance-criteria; this skill catalogs the whole feature's failure surface
• The feature is not specified enough to enumerate inputs, states, and limits -> use deliver-prd first
• A production incident already happened and you want the learning banked -> use iterate-lessons-log, then update this catalog with the new case
• You need readiness coordination for a launch, not failure analysis -> use deliver-launch-checklist

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 Format

Use the template in references/TEMPLATE.md to structure the output. A complete edge-case catalog fills every template section: Feature Overview; Edge Case Categories; Error Messages; Recovery Paths; and Test Scenarios.

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

Examples

See references/EXAMPLE.md for a completed example.

Scenario: profile-photo and document upload

This is the INPUT brief for an output-quality eval. The skill arm and the control arm each receive everything below (and nothing else about how to do the work) and produce an edge-case catalog for it. Judges never see this header.

Feature brief

Product: a consumer mobile + web app (a freelancer marketplace). Users upload a profile photo and up to 5 portfolio documents (PDF/PNG/JPG) when building their profile.

How it should work (intended behavior):

• Users pick files from the device (camera, photo library, or file picker) and see a thumbnail

preview before confirming.

• Profile photo: square crop, max 10 MB, JPG/PNG only.
• Portfolio documents: max 5 files, each up to 25 MB, PDF/PNG/JPG.
• Uploads show a progress bar and can be canceled mid-upload.
• A virus/malware scan runs server-side before a file is accepted.

Known constraints and concerns the team has raised:

• Mobile users are often on flaky cellular connections; an upload can stall or drop partway.
• Files can be corrupt, zero-byte, wrong type despite the extension, or **far over the

size limit**.

• A user can background the app or lock the phone mid-upload.
• The malware scan can fail, time out, or flag a file.
• Two devices logged into the same account can upload at the same time.
• Storage has a per-account quota; a 6th portfolio file or an over-quota upload must be handled.
• Image files can carry EXIF orientation and location metadata.
• The feature must be accessible (screen-reader labels for upload state, no color-only error

signaling) and work offline-to-online (queue then sync).

Explicitly out of scope: video upload, bulk/folder upload, and third-party cloud imports (Google Drive, Dropbox).

deliver-edge-cases - Version History

2.1.1 (2026-06-13)

Trigger-recall patch (M-31 finding B1): the trigger-eval baseline confirmed under-triggering on intent-only phrasings (no literal "edge case" keyword) on both Haiku (50% validation) and Sonnet (63% validation). The description and the "When to Use" section now name the common synonyms explicitly - failure modes, what can go wrong, race conditions, timeouts, and boundary or limit scenarios - so the router recognizes the domain when expressed in user language. Boundary pointers to deliver-acceptance-criteria, deliver-prd, iterate-lessons-log, and deliver-launch-checklist are unchanged. No body, template, or example changes beyond the one added "When to Use" bullet.

2.1.0 (2026-06-10)

Quality-convergence minor (F-12 Batch 1): added a "When NOT to Use" section with boundary pointers to neighboring skills, and the Output Format now enumerates the template sections a complete artifact fills. No template or example changes.

2.0.1 (2026-06-10)

Description-only patch (F-12 Batch 0, from the 2026-06-09 repo audit): the trigger-surface description was rewritten to disambiguate collision pairs with an explicit boundary pointer to the sibling skill. No body, template, or behavior changes.

2.0.0 (2026-01-26)

Baseline row for the prior published version; see git history for its changes.

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

Boundary Conditions

Error States

Concurrency

Integration Failures

Error Messages

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

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

Boundary Conditions

Error States

Concurrency

Integration Failures

Error Messages

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

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]