architecture/old/skills/issue-writing/SKILL.md

name, model, description, user-invocable

name	model	description	user-invocable
issue-writing	haiku	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.	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

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

- [ ] 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:

# 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

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

## Summary
What feature and why it's valuable.

## Acceptance Criteria
- [ ] ...

## User Story (optional)
As a [role], I want [capability] so that [benefit].

Technical Task

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

   ## Dependencies
   - Depends on #12 (must complete first)
   - Related to #15 (informational)
   

2. After creating the issue, formally link blockers using tea CLI:

   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.