user-story

Files (1)

• SKILL.md

SKILL.md (first lines)

# User Story Skill

Draft polished, Jira-ready User Stories with Acceptance Criteria following agile best practices.

---

## Output Format

Every user story must follow this exact structure:

```
**Title:** [Short, imperative-phrased summary — max 10 words]

**Type:** Story  
**Priority:** [Critical / High / Medium / Low]  
**Story Points:** [1 / 2 / 3 / 5 / 8 / 13 — Fibonacci scale]

---

**User Story**

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

---

**Acceptance Criteria**

---

**AC1 - [Criterion Name]**

Given [precondition],
When [action],
Then [expected outcome].

---

**AC2 - [Criterion Name]**

Given [precondition],
When [action],
Then [expected outcome].

---

[Add as many AC[N] - Name blocks as needed — minimum 3, maximum 8]

---

**Out of Scope**
- [What is explicitly NOT included in this story]

**Dependencies**
- [Any blockers, related tickets, or prerequisites — or "None"]

**Notes**
[Optional: edge cases, open questions, design links, or context for the dev team]
```

---

## Writing Guidelines

### Title
- Imperative verb ("Add", "Enable", "Display", "Allow", "Support")
- Never start with "As a user..."
- Specific enough to distinguish from other tickets at a glance

### Persona
- Be specific: prefer "logged-in customer", "admin user", "guest visitor" over generic "user"
- Match the persona to the system context if provided

### Story Statement (the "As a / I want / So that")
- "I want" = the feature action, not the business outcome
- "So that" = the *why* — business value, not just a restatement of I want
- Avoid technical implementation details in the story statement

### Acceptance Criteria (AC[N] - Name / Given/When/Then)
- Each criterion is labeled **AC[N] - Name** on its own line, where N is a sequential number and Name is a short descriptive title for the criterion
- The label is separated from the Given/When/Then block by a blank line
- Each criterion tests ONE behavior
- Given, When, and Then are each on their own line
- "Given" = system state or precondition
- "When" = the user action or event
- "Then" = the observable, verifiable outcome
- Use concrete, testable language — avoid vague words like "fast", "easy", "properly"
- Cover happy path first, then edge cases and error states
- Include at least one negative/error case (e.g., invalid input, missing permission)
- Separate each AC block with a horizontal rule (`---`) for markdown readability

### Story Points
Default guidance (adjust to context if user specifies team conventions):
- **1** — Trivial change, < 2 hours
- **2** — Simple, well-understood, < half a day
- **3** — Small feature, some unknowns, ~1 day
- **5** — Medium complexity, a few days
- **8** — Complex, multiple components, ~1 week
- **13** — Very large, consider splitting

### Priority
- **Critical** — Blocker, production issue, or must-have for launch
- **High** — Important for the current sprint goal
- **Medium** — Valuable, but not blocking
- **Low** — Nice-to-have, future consideration

---

## Behavior Rules

1. **Always produce a complete story** — never leave placeholders like "[describe here]". Make reasonable assumptions and note them in the Notes section.
2. **Ask before assuming** only if the user's input is genuinely too vague to produce any meaningful story. Otherwise, draft first and offer to refine.
3. **Split large features** — if the request describes multiple independent user journeys, produce multiple stories and flag that they should be separate Jira tickets.
4. **Match the user's domain** — use their terminology (e.g., "merchant", "patient", "student") rather than generic words.
5. **Never include implementation details** in the story statement. They belong in Notes or a separate technical task ticket.
6. **Markdown formatting** — output should be clean Markdown that renders well in Jira's description field. Use `**bold**` for section headers.

---

From craigspaterson/agent-skills, MIT.

More from craigspaterson/agent-skills