213 lines
5.5 KiB
Markdown
213 lines
5.5 KiB
Markdown
---
|
|
name: issue-writing
|
|
description: >
|
|
Write clear, actionable issues with user stories, vertical slices, and acceptance
|
|
criteria. Use when creating issues, writing bug reports, feature requests, or when
|
|
the user needs help structuring an issue.
|
|
user-invocable: false
|
|
---
|
|
|
|
# Issue Writing
|
|
|
|
How to write clear, actionable issues that deliver user value.
|
|
|
|
## Primary Format: User Story
|
|
|
|
Frame issues as user capabilities, not technical tasks:
|
|
|
|
```markdown
|
|
Title: As a [persona], I want to [action], so that [benefit]
|
|
|
|
## User Story
|
|
As a [persona], I want to [action], so that [benefit]
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Specific, testable requirement
|
|
- [ ] Another requirement
|
|
- [ ] User can verify this works
|
|
|
|
## Context
|
|
Additional background, links, or references.
|
|
|
|
## Technical Notes (optional)
|
|
Implementation hints or constraints.
|
|
```
|
|
|
|
**Example:**
|
|
```markdown
|
|
Title: As a domain expert, I want to save my diagram, so that I can resume work later
|
|
|
|
## User Story
|
|
As a domain expert, I want to save my diagram to the cloud, so that I can resume
|
|
work later from any device.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] User can click "Save" button in toolbar
|
|
- [ ] Diagram persists to cloud storage
|
|
- [ ] User sees confirmation message on successful save
|
|
- [ ] Saved diagram appears in recent files list
|
|
|
|
## Context
|
|
Users currently lose work when closing the browser. This is the #1 requested feature.
|
|
```
|
|
|
|
## Vertical Slices
|
|
|
|
Issues should be **vertical slices** that deliver user-visible value.
|
|
|
|
### The Demo Test
|
|
|
|
Before writing an issue, ask: **Can a user demo or test this independently?**
|
|
|
|
- **Yes** → Good issue scope
|
|
- **No** → Rethink the breakdown
|
|
|
|
### Good vs Bad Issue Titles
|
|
|
|
| Good (Vertical) | Bad (Horizontal) |
|
|
|-----------------|------------------|
|
|
| "As a user, I want to save my diagram" | "Add persistence layer" |
|
|
| "As a user, I want to see errors when login fails" | "Add error handling" |
|
|
| "As a domain expert, I want to list orders" | "Add query syntax to ADL" |
|
|
|
|
The technical work is the same, but vertical slices make success criteria clear and deliver demonstrable value.
|
|
|
|
## Writing User Stories
|
|
|
|
### Format
|
|
|
|
```
|
|
As a [persona], I want [capability], so that [benefit]
|
|
```
|
|
|
|
**Persona:** From manifesto or product vision (e.g., domain expert, developer, product owner)
|
|
|
|
**Capability:** What the user can do (not how it's implemented)
|
|
|
|
**Benefit:** Why this matters to the user
|
|
|
|
### Examples
|
|
|
|
```markdown
|
|
✓ As a developer, I want to run tests locally, so that I can verify changes before pushing
|
|
✓ As a product owner, I want to view open issues, so that I can prioritize work
|
|
✓ As a domain expert, I want to export my model as JSON, so that I can share it with my team
|
|
|
|
✗ As a developer, I want a test runner (missing benefit)
|
|
✗ I want to add authentication (missing persona and benefit)
|
|
✗ As a user, I want the system to be fast (not specific/testable)
|
|
```
|
|
|
|
## Acceptance Criteria
|
|
|
|
Good criteria are:
|
|
- **Specific**: "User sees error message" not "Handle errors"
|
|
- **Testable**: Can verify pass/fail
|
|
- **User-focused**: What the user experiences
|
|
- **Independent**: Each stands alone
|
|
|
|
**Examples:**
|
|
```markdown
|
|
- [ ] Login form validates email format before submission
|
|
- [ ] Invalid credentials show "Invalid email or password" message
|
|
- [ ] Successful login redirects to dashboard
|
|
- [ ] Session persists across browser refresh
|
|
```
|
|
|
|
## Alternative Formats
|
|
|
|
### Bug Report
|
|
|
|
```markdown
|
|
Title: Fix [specific problem] in [area]
|
|
|
|
## Summary
|
|
Description of the bug.
|
|
|
|
## Steps to Reproduce
|
|
1. Go to...
|
|
2. Click...
|
|
3. Observe...
|
|
|
|
## Expected Behavior
|
|
What should happen.
|
|
|
|
## Actual Behavior
|
|
What happens instead.
|
|
|
|
## Environment
|
|
- Browser/OS/Version
|
|
```
|
|
|
|
### Technical Task
|
|
|
|
Use sparingly - prefer user stories when possible.
|
|
|
|
```markdown
|
|
Title: [Action] [component/area]
|
|
|
|
## Summary
|
|
What technical work needs to be done and why.
|
|
|
|
## Scope
|
|
- Include: ...
|
|
- Exclude: ...
|
|
|
|
## Acceptance Criteria
|
|
- [ ] Measurable technical outcome
|
|
- [ ] Another measurable outcome
|
|
```
|
|
|
|
## Issue Sizing
|
|
|
|
Issues should be **small enough to complete in 1-3 days**.
|
|
|
|
**Too large?** Split into smaller vertical slices:
|
|
|
|
```markdown
|
|
# Too large
|
|
As a user, I want full authentication, so that my data is secure
|
|
|
|
# Better: Split into slices
|
|
1. As a user, I want to register with email/password, so that I can create an account
|
|
2. As a user, I want to log in with my credentials, so that I can access my data
|
|
3. As a user, I want to reset my password, so that I can regain access if I forget it
|
|
```
|
|
|
|
## Labels
|
|
|
|
Use labels to categorize:
|
|
- Type: `bug`, `feature`, `enhancement`, `refactor`
|
|
- Priority: `priority/high`, `priority/medium`, `priority/low`
|
|
- Component: Project-specific (e.g., `auth`, `api`, `ui`)
|
|
- DDD: `bounded-context/[name]`, `aggregate`, `command`, `event` (when applicable)
|
|
|
|
## Dependencies
|
|
|
|
Identify and link dependencies when creating issues:
|
|
|
|
1. **In the description**, document dependencies:
|
|
```markdown
|
|
## Dependencies
|
|
- Depends on #12 (must complete first)
|
|
- Related to #15 (informational)
|
|
```
|
|
|
|
2. **After creating the issue**, formally link blockers using tea CLI:
|
|
```bash
|
|
tea issues deps add <this-issue> <blocker-issue>
|
|
tea issues deps add 5 3 # Issue #5 is blocked by #3
|
|
```
|
|
|
|
This creates a formal dependency graph that tools can query.
|
|
|
|
## Anti-Patterns
|
|
|
|
**Avoid:**
|
|
- Generic titles: "Fix bugs", "Improve performance"
|
|
- Technical jargon without context: "Refactor service layer"
|
|
- Missing acceptance criteria
|
|
- Horizontal slices: "Build API", "Add database tables"
|
|
- Vague criteria: "Make it better", "Improve UX"
|
|
- Issues too large to complete in a sprint
|