| name | write-user-story |
| description | Create a well-structured user story with acceptance criteria, following project conventions and issue templates |
| inputs | [{"name":"feature_description","description":"Brief description of what the user wants to accomplish","required":true},{"name":"user_role","description":"The type of user (e.g., \"admin\", \"developer\", \"end user\")","required":false}] |
| outputs | [{"name":"user_story","description":"Complete user story with title, description, and acceptance criteria"}] |
Purpose
Guide the creation of consistent, actionable user stories that follow project conventions and leverage existing issue templates when available.
Preconditions
- Feature or capability has been discussed or requested
- User role and goal are understood at a high level
Steps
1. Check for existing issue templates
Search the repository for issue templates in common locations:
Primary locations to check:
.github/ISSUE_TEMPLATE/ directory (YAML or Markdown templates).github/ISSUE_TEMPLATE.md (single template file)docs/ISSUE_TEMPLATE.md (alternative location)
What to look for:
| File Pattern | Purpose |
|---|
feature_request.yml or feature_request.md | Use as primary structure basis |
bug_report.yml or bug_report.md | Note fields for cross-referencing |
config.yml | Check for blank issue restrictions or external links |
Custom templates (e.g., user_story.yml) | Follow established team conventions |
If templates exist:
- Read the template content to understand required fields
- Note any dropdown options, checkboxes, or validation rules
- Identify which template best fits a user story (usually feature request)
- Map your user story components to the template's structure
If no templates exist:
- Proceed with the standard format in Step 3
- Consider recommending an issue template as a follow-up improvement
2. Gather user story components
Collect the essential elements:
| Component | Question to Answer |
|---|
| User Role | Who is the user? Be specific (not just "user") |
| Goal | What does the user want to do? |
| Benefit | Why does the user want this? What value does it provide? |
| Context | What triggers this need? When would this be used? |
3. Draft the user story
Write using the standard format:
## User Story
**As a** [specific user role],
**I want** [goal/desire],
**So that** [benefit/value].
4. Define acceptance criteria
Write testable, specific acceptance criteria using Given/When/Then:
## Acceptance Criteria
### Scenario: [descriptive name]
- **Given** [precondition/context]
- **When** [action taken]
- **Then** [expected outcome]
Include criteria for:
5. Add supporting context
Include additional sections as needed:
## Technical Notes
- Dependencies: [related systems, APIs, services]
- Constraints: [technical limitations, regulatory requirements]
## Out of Scope
- [Explicitly list what this story does NOT include]
## Related
- Relates to #[issue number]
- Blocked by #[issue number]
- Part of Epic: [epic name/link]
6. Validate the story
Before finalizing, verify the story meets INVEST criteria:
| Criterion | Check |
|---|
| Independent | Can be developed without depending on other stories |
| Negotiable | Details can be discussed and refined |
| Valuable | Delivers value to the user or business |
| Estimable | Team can estimate the effort required |
| Small | Can be completed in one sprint/iteration |
| Testable | Acceptance criteria are verifiable |
7. Create the issue
If an issue template was found in step 1:
- Use the template structure
- Map user story components to template fields
- Fill in all required fields
If no template exists:
- Create issue with the drafted user story
- Consider proposing an issue template for future consistency
Completion Criteria
Examples
Example: Good User Story
## User Story
**As a** system administrator,
**I want** to receive email notifications when user accounts are locked,
**So that** I can proactively assist users and identify potential security issues.
## Acceptance Criteria
### Scenario: Account locked due to failed login attempts
- **Given** a user account exists in the system
- **When** the account is locked after 5 failed login attempts
- **Then** an email is sent to all system administrators within 1 minute
### Scenario: Email contains relevant details
- **Given** an account lock notification is triggered
- **When** the email is sent
- **Then** it includes: username, timestamp, IP address of attempts, and unlock link
### Scenario: Administrator is unavailable
- **Given** no administrator acknowledges the notification within 1 hour
- **When** the escalation timer expires
- **Then** the notification is escalated to the security team
## Technical Notes
- Integrates with existing email service (SendGrid)
- Must respect user notification preferences
- Audit log entry required for compliance
## Out of Scope
- Self-service account unlock (separate story)
- SMS notifications (future enhancement)
## Related
- Part of Epic: Account Security Improvements
- Relates to #142 (Audit logging)
Example: Poor User Story (Avoid)
## User Story
As a user, I want better notifications so that I know what's happening.
## Acceptance Criteria
- Notifications work
- Users are happy
Why this is poor: Vague user role, unclear goal, unmeasurable criteria.
References
