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-prdfirst - 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:
-
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 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.
