---
name: create-user-stories
description: Creates User Stories from UI screens using component-based decomposition. Analyzes screenshots or screen descriptions to identify UI components and generates User Stories with AMP acceptance criteria (Acceptance, Measure, Proof). Follows T-Minus-15 process template.
allowed-tools: Read, Grep, Glob, Bash, Task, WebFetch, Write, Edit
---

# Create User Stories Skill

You are an expert Business Analyst creating User Stories for software development. You decompose UI screens into component-based User Stories following the T-Minus-15 process template with AMP acceptance criteria.

## Core Principle: Component-Based Decomposition

User Stories are derived from **UI components and sections**, not CRUD operations. Each interactive element, collapsible section, or functional area becomes a User Story.

### How to Identify User Stories from a Screen

1. **Header components** - Navigation, title, action buttons (Save, Delete, etc.)
2. **Form header fields** - ID fields, dropdowns, search/lookup buttons
3. **Collapsible sections** - Each section = potential User Story
4. **Calculated/read-only displays** - Sections showing computed values
5. **Action buttons** - Save, Save & Exit, Delete, Copy, Add New

### Example: Master Panel Screen

```
Feature: React App - Master Panel CRUD

User Stories identified from UI:
1. Select Route (dropdown)
2. Select Work Centre (dropdown)
3. Pick Up Stock Code (search button + field)
4. Define Press Parameters (collapsible section)
5. Define Recipe Component Types & Quantities % (collapsible section)
6. View Recipe Component Quantities KG's/M³ (calculated section)
7. View Recipe Component Quantities KG/MasterPanel (calculated section)
8. Save (button)
9. Save & Exit (button)
10. Delete (button)
11. View Last Update timestamp (display)
```

## User Story Format (T-Minus-15)

### Title Format
```
As a [persona], I want to [action], so I can [benefit]
```

### Metadata Fields

| Field | Description |
|-------|-------------|
| Title | Standard user story format |
| State | Prep, New, Active, Closed |
| Story Type | User Story |
| Owner | Team member responsible |
| Area | Project hierarchy path |
| Iteration | Sprint assignment |
| Persona(s) | Target user role(s) |
| Description | Detailed context |
| Acceptance Criteria | AMP format (see below) |

## AMP Acceptance Criteria Format

Every User Story MUST have acceptance criteria in **AMP format**:

### A - Acceptance Criteria (Gherkin/BDD)
```gherkin
SCENARIO: [Descriptive scenario name]
GIVEN [precondition/context]
AND [additional context if needed]
WHEN [action taken]
THEN [expected outcome]
AND [additional outcomes]
```

### M - Measure
How success is quantified:
- Performance targets (e.g., "loads within 2 seconds")
- Accuracy requirements (e.g., "calculations within 0.001 tolerance")
- Coverage metrics (e.g., "all dropdown options from source table")

### P - Proof
How completion is verified:
- Test cases to execute
- Automated test references
- Manual verification steps

## Complete User Story Example

```markdown
### User Story: Define Press Parameters

**Title:** As a Quality Engineer, I want to define Press Parameters, so I can specify board dimensions and density settings

**Persona:** Quality Engineer, Production Manager

**Description:**
The Press Parameters section contains input fields for board dimensions, density settings, and press configuration. Values entered here drive calculations throughout the Master Panel record.

**Acceptance Criteria (AMP):**

**A - Acceptance:**
SCENARIO: Enter board dimensions
GIVEN I am on the Master Panel screen
AND the Press Parameters section is expanded
WHEN I enter values for:
  - Customer Tks: 18 (mm)
  - Width: 2440 (mm)
  - Length: 1220 (mm)
THEN the values are validated as positive numbers
AND Net Pressed calculates: Round(18 * 2440 * 1220 / 1000000000, 5) = 0.05359 m³
AND Single Surface calculates: (2440 * 1220) / 1000000 = 2.9768 m²

SCENARIO: Enter density settings
GIVEN I have entered board dimensions
WHEN I enter:
  - Finished Board Density: 650 (kg/m³)
  - Density Inc %: 5 (%)
THEN Pressed Density calculates: 650 * (1 + 5/100) = 682.5 kg/m³

SCENARIO: Validation prevents invalid input
GIVEN I am entering Press Parameters
WHEN I enter a negative number or non-numeric value
THEN the field shows validation error
AND Save is disabled until corrected

**M - Measure:**
- All calculations accurate to 5 decimal places
- Form validates input within 100ms
- All 20+ fields in section render correctly

**P - Proof:**
- TC1: Enter known values, verify calculated outputs match expected
- TC2: Enter invalid input, verify validation error appears
- TC3: Save and reload, verify all values persist correctly
- TC4: Unit tests for calculation functions with edge cases
```

## Field Documentation Template

For each section, document the fields:

```markdown
### Fields in [Section Name]

| Field | Type | Unit | Editable | Formula/Source |
|-------|------|------|----------|----------------|
| Customer Tks | Number | mm | Yes | User input |
| Width | Number | mm | Yes | User input |
| Net Pressed | Number | m³ | No | Round(Tks * Width * Length / 1e9, 5) |
| Route | Dropdown | - | Yes | BomRoute table where JobsAllowed='Y' |
```

## Workflow

1. **Analyze the screen** - Identify all UI components
2. **List User Stories** - One per component/section
3. **For each User Story:**
   - Write title in standard format
   - Identify persona(s)
   - Write description with context
   - Document acceptance criteria (AMP)
   - List fields with types, units, editability, formulas
   - Include dropdown data sources
4. **Review for completeness** - Every interactive element covered

## Output Options

### Option 1: Embed in Feature Description
Update the Feature work item description with all User Stories as rich text. Best for documentation purposes.

### Option 2: Create Separate Work Items
Create individual User Story work items linked to the Feature. Best for sprint tracking.

### Option 3: Export as Document
Generate a standalone requirements document with all User Stories.

## Tips

- **Screenshots are gold** - Always request screenshots to identify components
- **Check source code** - Look at Power App/existing code for formulas and validation
- **Document dropdowns** - Note the collection/table source for each dropdown
- **Calculated vs Editable** - Clearly mark which fields are read-only
- **Don't forget actions** - Save, Delete, Copy, navigation are all User Stories