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

name, description, user-invocable

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

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:

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

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

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

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.

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:

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

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

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