feat: add DDD capability for vision-to-issues workflow
Add complete DDD capability set for breaking down product vision into implementation issues using Domain-Driven Design principles. Components: - issue-writing skill: Enhanced with user story format and vertical slices - ddd skill: Strategic and tactical DDD patterns (bounded contexts, aggregates, commands, events) - ddd-breakdown skill: User-invocable workflow (/ddd-breakdown) - ddd-analyst agent: Analyzes manifesto/vision/code, generates DDD-structured user stories Workflow: Read manifesto + vision → analyze codebase → identify bounded contexts → map features to DDD patterns → generate user stories → create Gitea issues Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
212
skills/issue-writing/SKILL.md
Normal file
212
skills/issue-writing/SKILL.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
name: issue-writing
|
||||
description: >
|
||||
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.
|
||||
user-invocable: 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:
|
||||
|
||||
```markdown
|
||||
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:**
|
||||
```markdown
|
||||
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
|
||||
|
||||
```markdown
|
||||
✓ 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:**
|
||||
```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
|
||||
```
|
||||
|
||||
## Alternative Formats
|
||||
|
||||
### Bug Report
|
||||
|
||||
```markdown
|
||||
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.
|
||||
|
||||
```markdown
|
||||
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:
|
||||
|
||||
```markdown
|
||||
# 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:
|
||||
```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.
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user