Skip to content

majiayu000/spellbook / skills/prd-master

prd-master

Verified

PRD writing and product definition expert. Use when writing PRDs, user stories, acceptance criteria, or prioritizing features. Covers RICE/MoSCoW frameworks, agile requirements, and specification best practices.

FileKindSize
SKILL.mdskill md13.2 KB
reference/acceptance-criteria.mdmarkdown20.4 KB
reference/extended.mdmarkdown6.7 KB
reference/prioritization.mdmarkdown24.6 KB
reference/user-stories.mdmarkdown18.1 KB
templates/prd-template.mdmarkdown22.8 KB

reference/user-stories.md

View on GitHub
# User Story Writing Guide

## Overview

User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability. They follow the format:

```
As a [persona/role],
I want to [action/goal],
So that [benefit/value].
```

User stories are intentionally brief because they're meant to spark detailed discussions between the development team, product owner, and stakeholders.

---

## The Three C's Framework

### 1. Card

The "Card" represents the physical or digital card containing the user story statement. Originally, Agile teams wrote stories on index cards to emphasize their simplicity and portability.

**Purpose:**
- Placeholder for conversation
- Quick reference during planning
- Easy to reorganize and prioritize

**Example Card:**
```
As a returning customer,
I want one-click reordering of past purchases,
So that I can save time on frequent orders.
```

### 2. Conversation

The "Conversation" is the most critical element. User stories are brief because detailed requirements emerge through discussion.

**Key conversations:**
- Why is this valuable to users?
- What are the edge cases?
- What are the technical constraints?
- How does this integrate with existing features?
- What happens when things go wrong?

**Example Discussion Points:**
```
Story: One-click reordering

Questions to discuss:
- Q: How far back in order history can users reorder?
- A: Last 12 months, up to 100 most recent orders

- Q: What if an item is out of stock?
- A: Show substitution suggestions or remove from cart with notification

- Q: Do we modify quantities or use original order exactly?
- A: Use original, but allow editing before checkout

- Q: How do we handle price changes?
- A: Show current price, indicate if different from original order
```

### 3. Confirmation

The "Confirmation" involves the acceptance criteria that define when a story is complete.

**Format:** Given-When-Then (see acceptance-criteria.md)

**Example:**
```
Acceptance Criteria:

Given I'm viewing my order history
When I click "Reorder" on a past order
Then all available items are added to my cart
And out-of-stock items show substitution suggestions
And I see a summary: "12 items added, 2 unavailable"

Given items in my cart from reorder
When I proceed to checkout
Then I see current prices (with indicators if changed)
And I can edit quantities before payment
```

---

## INVEST Criteria

Good user stories follow INVEST principles:

### Independent

Stories should stand alone with minimal dependencies on other stories.

```
❌ Dependent:
Story 1: "Create user profile database table"
Story 2: "Add user profile UI" (depends on Story 1)

✓ Independent:
"As a user, I want to create and edit my profile"
(Implementation details emerge in conversation)
```

### Negotiable

Details are flexible and emerge through conversation. Stories are not rigid contracts.

```
❌ Too prescriptive:
"As a user, I want a blue button in the top-right corner that opens
a modal dialog with a form containing Name, Email, and Bio fields
limited to 500 characters with a Save button that calls POST /api/profile"

✓ Negotiable:
"As a user, I want to update my profile information (name, email, bio)
so that others can learn about me"

→ UI design and implementation details are discussed later
```

### Valuable

Every story must deliver value to users or the business.

```
❌ No clear value:
"As a developer, I want to refactor the authentication module"

✓ Valuable:
"As a user, I want faster login (< 2s) so I can access my account quickly"

Note: Technical work is valid but frame it in terms of user/business value
```

### Estimable

The team must be able to estimate the effort required.

```
❌ Too vague to estimate:
"As a user, I want the system to be intelligent"

✓ Estimable:
"As a user, I want product recommendations based on my browsing history"

If story is not estimable:
- Break it down into smaller stories
- Do a spike/research story first
- Clarify unknowns through conversation
```

### Small

Stories should be completable within one sprint (typically 1-2 weeks).

```
❌ Too large (Epic):
"As a customer, I want a complete e-commerce checkout experience"

✓ Small stories:
- "As a customer, I want to add items to my shopping cart"
- "As a customer, I want to enter shipping address"
- "As a customer, I want to select payment method"
- "As a customer, I want to review order before purchase"
- "As a customer, I want to receive order confirmation"
```

### Testable

Clear acceptance criteria make stories testable.

```
❌ Not testable:
"As a user, I want a good search experience"

✓ Testable:
"As a user, I want search results within 500ms
with at least 90% relevance for common queries"

Acceptance criteria:
- Given I search for "laptop"
- When results load
- Then I see results within 500ms (p95)
- And top 5 results match "laptop" category
```

---

## User Story Templates

### Standard Template

```
As a [persona/role],
I want to [action/goal],
So that [benefit/value].
```

### Job-to-be-Done Template

```
When [situation],
I want to [action],
So I can [outcome].
```

**Example:**
```
When I'm shopping for gifts during the holidays,
I want to filter by price range and recipient age,
So I can quickly find appropriate gifts within budget.
```

### Feature-Driven Template

```
In order to [benefit],
As a [persona/role],
I want [action/goal].
```

**Example:**
```
In order to reduce cart abandonment,
As a product manager,
I want to offer guest checkout without account creation.
```

---

## Examples by Domain

### E-commerce

```
Story: Guest Checkout
As a first-time visitor,
I want to checkout without creating an account,
So that I can complete my purchase quickly.

Acceptance Criteria:
- Given I have items in cart and I'm not logged in
- When I click "Checkout"
- Then I see option: "Continue as Guest" or "Login"
- And I can complete purchase with just email, shipping, payment
- And I receive confirmation email with order tracking

---

Story: Wishlist
As a registered user,
I want to save items to a wishlist,
So that I can purchase them later or share with others.

Acceptance Criteria:
- Given I'm viewing a product
- When I click "Add to Wishlist" (heart icon)
- Then the item is saved to my wishlist
- And I can view all wishlist items on dedicated page
- And I can share wishlist via unique URL
- And I can move items from wishlist to cart
```

### SaaS Application

```
Story: SSO Integration
As an enterprise admin,
I want to enable Single Sign-On via SAML,
So that my team can access the app using company credentials.

Acceptance Criteria:
- Given I'm an account admin
- When I navigate to Settings > Authentication
- Then I can upload SAML metadata XML or enter IdP URL
- And I can test connection before enabling
- And I can require SSO for all team members
- And users see "Login with SSO" option on login page

---

Story: Usage Analytics
As a team lead,
I want to see which features my team uses most,
So that I can optimize workflows and training.

Acceptance Criteria:
- Given I'm on the Analytics dashboard
- When I select date range (last 7/30/90 days)
- Then I see top 10 features by usage count
- And I see per-user activity breakdown
- And I can export data as CSV
```

### Mobile App

```
Story: Offline Mode
As a mobile user with unreliable connectivity,
I want to access recent content offline,
So that I can work without internet.

Acceptance Criteria:
- Given I've viewed content while online
- When I lose internet connection
- Then I can still access last 50 viewed items
- And I see indicator: "Offline mode - showing cached content"
- And my edits sync automatically when connection restored

---

Story: Push Notifications
As a user who wants to stay updated,
I want to receive push notifications for important events,
So that I don't miss time-sensitive information.

Acceptance Criteria:
- Given I've enabled notifications in settings
- When a relevant event occurs (message, mention, deadline)
- Then I receive push notification on my device
- And tapping notification opens relevant screen
- And I can customize notification types in settings
```

---

## Breaking Down Epics

### Epic Decomposition Process

```
1. Identify the Epic
   "Enable marketplace for third-party sellers"

2. List major capabilities
   - Seller registration and verification
   - Product listing management
   - Order fulfillment
   - Payment processing
   - Seller analytics

3. Break into user stories
   For each capability, write stories from different perspectives

4. Prioritize using MoSCoW or RICE
   Determine which stories are MVP vs future phases
```

### Example: Marketplace Epic

```
Epic: Enable Marketplace for Third-Party Sellers

Must Have (MVP):
- As a seller, I want to register and verify my business
- As a seller, I want to list products with photos and descriptions
- As a buyer, I want to see which products are from third-party sellers
- As a seller, I want to receive notification of new orders
- As a buyer, I want to contact sellers with questions
- As a seller, I want to receive payment for fulfilled orders
- As platform admin, I want to review and approve new sellers

Should Have (Phase 2):
- As a seller, I want to bulk upload products via CSV
- As a seller, I want analytics on views and sales
- As a buyer, I want to filter by seller rating
- As a seller, I want to offer promotions and discounts
- As platform admin, I want to charge commission on sales

Could Have (Phase 3):
- As a seller, I want to integrate inventory with my existing system
- As a seller, I want to A/B test product descriptions
- As a buyer, I want to follow favorite sellers
- As a seller, I want automated repricing based on competition

Won't Have (Future):
- As a seller, I want to open a physical storefront
- Integration with international payment processors
```

---

## User Story Mapping

User story mapping helps visualize the user journey and identify all necessary stories.

### Structure

```
┌─────────────────────────────────────────────────────────────┐
│                    User Activities (Top Row)                 │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   Discover   │   Evaluate   │   Purchase   │   Use/Support  │
├──────────────┼──────────────┼──────────────┼────────────────┤
│              │              │              │                │
│  Stories     │  Stories     │  Stories     │   Stories      │
│  (vertical)  │  (vertical)  │  (vertical)  │   (vertical)   │
│              │              │              │                │
│  ↓ MVP       │  ↓ MVP       │  ↓ MVP       │   ↓ MVP        │
│  ↓ Phase 2   │  ↓ Phase 2   │  ↓ Phase 2   │   ↓ Phase 2    │
│  ↓ Phase 3   │  ↓ Phase 3   │  ↓ Phase 3   │   ↓ Phase 3    │
└──────────────┴──────────────┴──────────────┴────────────────┘

Horizontal: User journey (left to right)
Vertical: Priority (top = MVP, bottom = nice-to-have)
```

### Example: Online Course Platform

```
Activity: Discover
MVP:
- Browse course catalog
- Search by keyword
- Filter by category
Phase 2:
- Personalized recommendations
- Course previews (video)
Phase 3:
- AI-powered course suggestions

Activity: Evaluate
MVP:
- View course details
- Read course reviews
- See instructor bio
Phase 2:
- Compare courses side-by-side
- Preview first lesson free
Phase 3:
- AI-generated course summaries

Activity: Purchase
MVP:
- Add course to cart
- Checkout with credit card
- Receive confirmation email
Phase 2:
- Apply discount codes
- Gift courses to others
Phase 3:
- Subscription bundles
- Corporate/team purchases

Activity: Learn
MVP:
- Watch video lessons
- Track progress
- Download course materials
Phase 2:
- Take quizzes
- Certificate of completion
- Discussion forums
Phase 3:
- Live Q&A sessions
- Peer code review
- Offline mobile app
```

---

## Common Mistakes

### 1. Too Technical

```
❌ "As a developer, I want to implement OAuth2 with JWT tokens"

✓ "As a user, I want to login securely without remembering multiple passwords,
   so I can access my account from any device"

Why: Focus on user value, not implementation details
```

### 2. Too Vague

```
❌ "As a user, I want the system to be fast"

✓ "As a user, I want search results to load within 500ms,
   so I can quickly find products without waiting"

Why: Vague stories aren't testable or estimable
```

### 3. Missing the "So That"

```
❌ "As a user, I want to filter products by price range"

✓ "As a budget-conscious shopper, I want to filter products by price range,
   so I only see items I can afford"

Why: The benefit clarifies the value and helps prioritization
```

### 4. Multiple Stories in One

```
❌ "As a user, I want to create an account, update my profile,
    change my password, and delete my account"

✓ Split into 4 stories:
- "As a new user, I want to create an account with email and password"
- "As a user, I want to update my profile information (name, bio, photo)"
- "As a user, I want to change my password for security"
- "As a user, I want to delete my account and all associated data"

Why: Smaller stories are easier to estimate, test, and complete
```

### 5. Implementation over Outcome

```
❌ "As a user, I want a dropdown menu in the navigation bar"

✓ "As a user, I want to easily navigate to different product categories,
   so I can browse relevant items"

Why: Let the team determine the best implementation (dropdown, mega menu, sidebar, etc.)
```

---

## User Story Workflow

### 1. Ideation

```
Sources:
- User research and interviews
- Customer support tickets
- Product analytics
- Competitive analysis
- Stakeholder requests
- Technical improvements

Capture in product backlog (unsorted)
```

### 2. Elaboration

```
During backlog refinement:
- Write user story in standard format
- Add context and rationale
- Identify acceptance criteria (draft)
- Attach design mockups (if available)
- List dependencies
```

### 3. Estimation

```
Team estimates effort:
- Planning poker (Fibonacci: 1, 2, 3, 5, 8, 13)
- T-shirt sizes (S, M, L, XL)
- Ideal days/hours

If estimate is too high → break down further
If too uncertain → create research spike
```

### 4. Prioritization

```
Apply prioritization framework:
- RICE scoring
- MoSCoW categorization
- Business value vs effort matrix

Move to sprint backlog when ready
```

### 5. Implementation

```
During sprint:
- Developer picks story from sprint backlog
- Discusses details with PM/designer
- Implements functionality
- Writes automated tests
- Creates pull request

Definition of Done:
- [ ] Code complete and reviewed
- [ ] Unit tests written (>80% coverage)
- [ ] Acceptance criteria verified
- [ ] No critical bugs
- [ ] Documentation updated
- [ ] Deployed to staging
```

### 6. Acceptance

```
Product owner verifies:
- All acceptance criteria met
- Edge cases handled
- Performance acceptable
- Accessible (WCAG 2.2 AA)

If approved → mark as Done
If issues found → create bug stories
```

---

## Tools for User Stories

| Tool | Best For | Key Features |
|------|----------|--------------|
| **Jira** | Enterprise Agile | Epics, stories, sprints, workflows |
| **Linear** | Engineering-focused teams | Fast, clean UI, GitHub integration |
| **Shortcut** | Small-medium teams | Simple, visual, story mapping |
| **Azure DevOps** | Microsoft ecosystem | Full ALM, backlogs, boards |
| **Pivotal Tracker** | Agile purists | Story points, velocity tracking |
| **Trello** | Simple projects | Kanban boards, easy collaboration |
| **ClickUp** | All-in-one | Docs, tasks, goals, time tracking |

---

## Best Practices

### 1. Write from User Perspective

```
✓ "As a customer, I want..."
✓ "As a seller, I want..."
✓ "As an admin, I want..."

Avoid:
✗ "The system shall..."
✗ "As a developer, I want..." (unless building dev tools)
```

### 2. Focus on One Persona per Story

```
❌ "As a buyer or seller, I want to message each other"

✓ Split into two perspectives:
- "As a buyer, I want to message the seller with questions about a product"
- "As a seller, I want to respond to buyer messages to increase sales"
```

### 3. Avoid UI Specifications

```
❌ "As a user, I want a red button labeled 'Submit' in the bottom-right corner"

✓ "As a user, I want to easily submit my form and receive confirmation"

Let design determine the UI implementation
```

### 4. Include Acceptance Criteria Early

```
Don't wait until sprint planning to add acceptance criteria.
Draft them during backlog refinement so the team can estimate accurately.

Basic draft is OK, details emerge during implementation.
```

### 5. Keep the Backlog Groomed

```
Regular refinement (weekly):
- Remove obsolete stories
- Break down large stories
- Update priorities
- Add missing acceptance criteria
- Clarify ambiguities

Goal: 2-3 sprints of refined stories ready to pull
```

### 6. Link to Supporting Artifacts

```
Attach to user story:
- Design mockups (Figma, Sketch)
- User research findings
- Analytics data
- Technical specs
- API documentation
- Related PRD sections
```

---

## Checklist

```markdown
## User Story Quality Check

### Format
- [ ] Follows "As a / I want / So that" format
- [ ] Written from user perspective (not system/developer)
- [ ] Includes clear benefit/value in "so that" clause

### INVEST Criteria
- [ ] Independent: Minimal dependencies
- [ ] Negotiable: Details flexible, not prescriptive
- [ ] Valuable: Clear user or business value
- [ ] Estimable: Team can estimate effort
- [ ] Small: Completable in one sprint
- [ ] Testable: Has acceptance criteria

### Acceptance Criteria
- [ ] Uses Given-When-Then format
- [ ] Covers happy path
- [ ] Includes error scenarios
- [ ] Defines edge cases
- [ ] Measurable and testable

### Supporting Information
- [ ] Context and rationale provided
- [ ] Link to designs (if available)
- [ ] Dependencies identified
- [ ] Estimated by team
- [ ] Prioritized in backlog
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall