---
name: issue-writing
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.