Questions to gather:
1. Which PRD/user story does this feature implement?
2. What's the single-sentence feature description?
3. Who is the primary user persona?
4. What technical constraints exist?
5. What's the target implementation timeline?

**Feature:** [Verb] [what] for [whom] to [achieve outcome]

Examples:
✅ "Display shipping cost estimates on product pages for shoppers to compare options before checkout"
✅ "Allow admins to create custom permission roles to match their organization structure"
✅ "Send real-time push notifications for transactions to help users detect fraud immediately"

❌ "Improve the shipping experience" (too vague)
❌ "Add role management" (missing who and why)

## Primary User Story

**As a** [specific user type]
**I want** [specific goal]
**So that** [concrete benefit]

## Story Variants (if applicable)

**Variant A - [Scenario Name]:**
As a [user], I want [alternative goal], so that [benefit]

**Variant B - [Scenario Name]:**
As a [user], I want [different goal], so that [benefit]

## Acceptance Criteria

### Happy Path
Scenario: Successful [action]
  Given [precondition]
  And [additional context]
  When [user action]
  Then [expected outcome]
  And [additional outcome]

### Validation
Scenario: Invalid [input type]
  Given [context]
  When [user provides invalid input]
  Then [validation message shown]
  And [action is prevented]

### Edge Cases
Scenario: [Boundary condition]
  Given [edge case setup]
  When [action at boundary]
  Then [expected behavior]

### Error Handling
Scenario: [Failure type]
  Given [normal context]
  And [dependency fails]
  When [user action]
  Then [graceful degradation]
  And [user informed of issue]

### Performance
Scenario: Response time under load
  Given [load conditions]
  When [action performed]
  Then [response within X ms]

### Security
Scenario: Unauthorized access attempt
  Given [user without permission]
  When [user attempts action]
  Then [access denied]
  And [attempt logged]

## Error States

| Error Condition | User Message | System Action | Recovery |
|-----------------|--------------|---------------|----------|
| Invalid input | "Please enter valid X" | Highlight field | User corrects |
| Network failure | "Connection lost. Retrying..." | Auto-retry 3x | Manual retry button |
| Server error | "Something went wrong" | Log error, alert oncall | Show support contact |
| Timeout | "Taking too long" | Cancel request | Offer retry |
| Not found | "Item not available" | 404 response | Suggest alternatives |
| Unauthorized | "Access denied" | 403 response | Redirect to login |
| Rate limited | "Too many requests" | 429 response | Show wait time |

## UI/UX Notes

### User Flow
1. Entry point: [Where user starts]
2. Key interactions: [Click, type, swipe, etc.]
3. Exit points: [Where user ends up]

### Responsive Behavior
- Desktop: [Layout/behavior]
- Tablet: [Adaptations]
- Mobile: [Mobile-specific behavior]

### Loading States
- Initial load: [Skeleton/spinner]
- Action pending: [Button state, progress]
- Background refresh: [Indicator]

### Empty States
- No data: [What to show]
- Error state: [Recovery UI]
- First-time user: [Onboarding]

### Accessibility
- Keyboard navigation: [Tab order, shortcuts]
- Screen reader: [ARIA labels, announcements]
- Color contrast: [WCAG AA compliance]

## Technical Constraints

### Dependencies
| Dependency | Type | Status | Owner |
|------------|------|--------|-------|
| [API/Service] | Internal | Ready/Pending | [Team] |
| [Third-party] | External | Integrated/Pending | [Vendor] |

### Limitations
- [Technical limitation 1 and workaround]
- [Technical limitation 2 and workaround]

### Non-Functional Requirements
| Requirement | Target | Measurement |
|-------------|--------|-------------|
| Response time | < 200ms p95 | APM |
| Availability | 99.9% | Monitoring |
| Throughput | 1000 req/s | Load test |

### Data Requirements
- Input: [Data types, formats, sizes]
- Output: [Response format, caching]
- Storage: [Persistence requirements]

As a shopper browsing the catalog,
I want to preview product details without leaving the page,
so that I can quickly evaluate products and continue browsing.

Scenario: Quick view on hover
  Given I am on the product catalog page
  When I hover over a product card for 500ms
  Then a quick view modal appears
  And shows product image, name, price, and sizes
  And shows "Add to Cart" and "View Details" buttons

Scenario: Quick view on mobile
  Given I am on mobile device
  When I tap the quick view icon on a product card
  Then a bottom sheet slides up with product details

Scenario: Image gallery in quick view
  Given the quick view modal is open
  When I click the next arrow
  Then the next product image displays
  And current position indicator updates

As an organization admin,
I want to configure exactly what each role can access,
so that I can enforce our security policies.

Variant A - Bulk Permission Update:
As an admin managing many roles,
I want to update permissions across multiple roles at once,
so that I can efficiently apply policy changes.

Variant B - Permission Templates:
As an admin setting up a new role,
I want to start from a template,
so that I don't have to configure from scratch.

Scenario: Grant permission to role
  Given I am editing the "Manager" role
  And I expand the "Reports" permission group
  When I toggle "View Financial Reports" to enabled
  Then the permission is added to the role
  And a "Save Changes" button appears
  And no changes are persisted until I click Save

Scenario: Permission dependency
  Given "Edit Reports" requires "View Reports"
  When I enable "Edit Reports"
  Then "View Reports" is automatically enabled
  And shows "Required by Edit Reports" tooltip

Scenario: Conflicting permissions
  Given the role has "View All Data"
  When I try to add "Restrict to Own Data"
  Then a conflict warning appears
  And I must resolve before saving

As a cardholder who received a suspicious transaction alert,
I want to dispute the charge immediately from the notification,
so that I can protect my account without calling support.

Scenario: Initiate dispute from alert
  Given I received a transaction alert
  When I tap "Dispute This Charge"
  Then I see dispute reason options
  And can select "Fraudulent", "Duplicate", "Not Received", "Other"

Scenario: Upload supporting documents
  Given I selected "Not Received" as dispute reason
  When I reach the evidence step
  Then I can upload photos or documents
  And supported formats are JPG, PNG, PDF
  And max file size is 10MB

Scenario: Dispute submission confirmation
  Given I completed all dispute steps
  When I tap "Submit Dispute"
  Then I see confirmation with case number
  And I receive email confirmation
  And card is temporarily frozen pending review

❌ "User authentication feature" (multiple features bundled)
✅ "Password reset via email flow" (single, focused feature)

❌ Only documenting happy path
✅ Including validation, errors, timeouts, rate limits

❌ "User can see products quickly"
✅ "Quick view modal appears within 300ms of hover"

❌ Assuming everything works
✅ Documenting what happens when things fail

❌ "Use Redis for caching with 5-minute TTL"
✅ "Response should be cached for improved performance"
(Save implementation details for technical spec)