diff --git a/skills/issue-writing/SKILL.md b/skills/issue-writing/SKILL.md index 9783428..c1371a6 100644 --- a/skills/issue-writing/SKILL.md +++ b/skills/issue-writing/SKILL.md @@ -49,6 +49,39 @@ Examples: - [ ] 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 diff --git a/skills/roadmap-planning/SKILL.md b/skills/roadmap-planning/SKILL.md index 2c89f8c..cab87cc 100644 --- a/skills/roadmap-planning/SKILL.md +++ b/skills/roadmap-planning/SKILL.md @@ -33,6 +33,48 @@ How to plan features and create issues for implementation. - Reference dependencies explicitly - Use consistent labeling +## Vertical vs Horizontal Slices + +**Prefer vertical slices** - each issue should deliver user-visible value. + +| Vertical (Good) | Horizontal (Bad) | +|-----------------|------------------| +| "User can save and reload their diagram" | "Add persistence layer" + "Add save API" + "Add load API" | +| "Domain expert can list all orders" | "Add query syntax to ADL" + "Add query runtime" + "Add query UI" | +| "User can reset forgotten password" | "Add email service" + "Add reset token model" + "Add reset form" | + +### The Demo Test + +Ask: **Can a user demo or test this issue independently?** + +- **Yes** → Good vertical slice +- **No** → Probably a horizontal slice, break differently + +### Break by User Capability, Not Technical Layer + +Instead of thinking "what technical components do we need?", think "what can the user do after this issue is done?" + +``` +# Bad: Technical layers +├── Add database schema +├── Add API endpoint +├── Add frontend form + +# Good: User capabilities +├── User can create a draft +├── User can publish the draft +├── User can edit published content +``` + +### When Horizontal Slices Are Acceptable + +Sometimes horizontal slices are necessary: +- **Infrastructure setup** - Database, CI/CD, deployment (do once, enables everything) +- **Security foundations** - Auth system before any protected features +- **Shared libraries** - When multiple features need the same foundation + +Even then, keep them minimal and follow immediately with vertical slices that use them. + ## Breaking Down Features ### By Layer