---
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
```

## 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.