Hugo Nijhuis
bbd7870483
Set explicit model preferences to optimize for speed vs capability: - haiku: 11 commands, 2 agents (issue-worker, pr-fixer), 10 skills Fast execution for straightforward tasks - sonnet: 4 commands (groom, improve, plan-issues, review-pr), 1 agent (code-reviewer) Better judgment for analysis and review tasks - opus: 2 commands (arch-refine-issue, arch-review-repo), 1 agent (software-architect) Deep reasoning for architectural analysis Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
158 lines
3.4 KiB
Markdown
158 lines
3.4 KiB
Markdown
---
|
|
name: issue-writing
|
|
model: haiku
|
|
description: Write clear, actionable issues with proper structure 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.
|
|
|
|
## Issue Structure
|
|
|
|
### Title
|
|
- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
|
|
- Be specific: "Add user authentication" not "Auth stuff"
|
|
- Keep under 60 characters when possible
|
|
|
|
### Description
|
|
|
|
```markdown
|
|
## Summary
|
|
One paragraph explaining what and why.
|
|
|
|
## 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.
|
|
```
|
|
|
|
## Writing 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
|
|
```
|
|
|
|
## 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) |
|
|
|-----------------|------------------|
|
|
| "User can save and reload diagram" | "Add persistence layer" |
|
|
| "Show error when login fails" | "Add error handling" |
|
|
| "Domain expert can list orders" | "Add query syntax to ADL" |
|
|
|
|
### Writing User-Focused Issues
|
|
|
|
Frame issues around user capabilities:
|
|
|
|
```markdown
|
|
# Bad: Technical task
|
|
Title: Add email service integration
|
|
|
|
# Good: User capability
|
|
Title: User receives confirmation email after signup
|
|
```
|
|
|
|
The technical work is the same, but the good title makes success criteria clear.
|
|
|
|
## Issue Types
|
|
|
|
### Bug Report
|
|
```markdown
|
|
## 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
|
|
```
|
|
|
|
### Feature Request
|
|
```markdown
|
|
## Summary
|
|
What feature and why it's valuable.
|
|
|
|
## Acceptance Criteria
|
|
- [ ] ...
|
|
|
|
## User Story (optional)
|
|
As a [role], I want [capability] so that [benefit].
|
|
```
|
|
|
|
### Technical Task
|
|
```markdown
|
|
## Summary
|
|
What technical work needs to be done.
|
|
|
|
## Scope
|
|
- Include: ...
|
|
- Exclude: ...
|
|
|
|
## Acceptance Criteria
|
|
- [ ] ...
|
|
```
|
|
|
|
## Labels
|
|
|
|
Use labels to categorize:
|
|
- `bug`, `feature`, `enhancement`, `refactor`
|
|
- `priority/high`, `priority/low`
|
|
- Component labels specific to project
|
|
|
|
## 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.
|