sprint-planning

Sprint & Release Planning

This skill helps you run effective planning processes — from writing good user stories to building quarterly roadmaps. Adapt the level of formality to your team's size and culture.

Before producing any planning output, read ../quality-standard/SKILL.md and apply its self-verification protocol, decomposition rules, and edge case prompting.

User Story Writing

A well-written story communicates intent without over-prescribing implementation. Every story MUST be production-ready with no ambiguity or missing acceptance criteria.

Format

As a [type of user],
I want to [action/capability],
so that [benefit/value].

Mandatory Story Requirements

Every story MUST include ALL of the following before it enters a sprint:

1. Acceptance Criteria (minimum 3 scenarios) in Given-When-Then format

   • Happy path scenario (the normal case)
   • At least one error/failure scenario
   • At least one edge case or boundary scenario

2. Definition of Done checklist (concrete, testable items)

   • Code reviewed
   • Tests written and passing
   • Acceptance criteria verified
   • Documentation updated
   • No console errors/warnings
   • (Add team-specific items)

3. Dependencies (explicit list)

   • Other stories that must complete first
   • External APIs or services required
   • Data or configuration changes needed
   • Third-party integrations

4. Estimated Complexity (S/M/L or story points)

   • Use Fibonacci: 1, 2, 3, 5, 8, 13
   • If >8, story is too large — split it

5. Story Quality Checklist (INVEST)

   • Independent — Minimal coupling to other stories
   • Negotiable — Implementation approach is flexible
   • Valuable — Delivers measurable user or business value
   • Estimable — Team can estimate within a confidence range
   • Small — Completable in ≤1 sprint
   • Testable — Acceptance criteria are verifiable

Complete Example: Add PIX Payment Method

Title: Add PIX payment method to checkout flow

As a Brazilian customer,
I want to pay with PIX at checkout,
so that I can use my preferred, instant payment method without credit card fees.

## Acceptance Criteria

### Happy Path
Given a customer with a valid PIX key in their payment methods,
When they select PIX at checkout and complete the payment flow,
Then the payment processes instantly, they receive an order confirmation email
within 2 minutes, and the order status shows "Paid" in their account.

### Error Case: Invalid PIX Key
Given a customer enters an invalid PIX key during payment,
When they submit the payment form,
Then the system displays "Invalid PIX key format" error message,
highlights the input field in red, and suggests the correct format (email, phone, CPF, or random key).

### Edge Case: Duplicate Payment Attempt (Race Condition)
Given a customer has submitted a PIX payment but clicks "Submit" again immediately,
When the system processes both requests concurrently,
Then only one charge is applied, a duplicate prevention lock is acquired,
and the customer is informed "Payment already processing—do not refresh."

### Boundary Case: Large Transaction Amount
Given a customer attempts to pay R$50,000 via PIX,
When the transaction exceeds the PIX single-transfer limit (R$4,992),
Then the system displays "Amount exceeds PIX limit" and offers to split into multiple transfers
or suggests alternative payment methods.

### Boundary Case: Very Quick Payment
Given a customer completes PIX payment verification in <100ms,
When the webhook callback arrives from the payment processor,
Then the order status updates to "Paid" without race conditions
and the confirmation email is queued correctly.

## Definition of Done
- [ ] PIX payment method integrated with payment processor (Stripe/PagSeguro/equivalent)
- [ ] Checkout UI updated to show PIX as option with logo
- [ ] All 5 acceptance criteria scenarios tested (manual + automated)
- [ ] Idempotency keys implemented to prevent duplicate charges
- [ ] Webhook handler for payment status updates tested with 50+ mock scenarios
- [ ] Error messages user-friendly and match brand tone
- [ ] No console errors/warnings in Chrome DevTools
- [ ] Documentation updated: README, API docs, payment flow diagram
- [ ] Database migrations tested on staging
- [ ] Metrics added: PIX transaction success rate, average completion time
- [ ] Backwards-compatible with existing payment methods
- [ ] Security review: no sensitive PIX keys stored in logs
- [ ] Load tested with 100+ concurrent PIX transactions

## Dependencies
- Payment processor account with PIX support enabled
- Webhook signing key from payment provider
- Legal/compliance review (PIX is regulated in Brazil)
- Frontend form validation library already in place
- Database schema supports new `payment_method` type

## Estimated Complexity
M (5 story points)
- Medium because: new payment provider integration + webhook handling + race condition handling
- Not small due to concurrency complexity
- Not large because PIX API is simpler than some alternatives