architecture/skills/roadmap-planning/SKILL.md

name, description, user-invocable

name	description	user-invocable
roadmap-planning	Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.	false

Roadmap Planning

How to plan features and create issues for implementation.

Planning Process

1. Understand the Goal

• What capability or improvement is needed?
• Who benefits and how?
• What's the success criteria?

2. Break Down the Work

• Identify distinct components
• Define boundaries between pieces
• Aim for issues that are:
  • Completable in 1-3 focused sessions
  • Independently testable
  • Clear in scope

3. Identify Dependencies

• Which pieces must come first?
• What can be parallelized?
• Are there external blockers?

4. Create Issues

• Follow issue-writing patterns
• 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

Feature: User Authentication
├── Data layer: User model, password hashing
├── API layer: Login/logout endpoints
├── UI layer: Login form, session display
└── Integration: Connect all layers

By User Story

Feature: Shopping Cart
├── Add item to cart
├── View cart contents
├── Update quantities
├── Remove items
└── Proceed to checkout

By Technical Component

Feature: Real-time Updates
├── WebSocket server setup
├── Client connection handling
├── Message protocol
├── Reconnection logic
└── Integration tests

Issue Ordering

Dependency Chain

Create issues in implementation order:

1. Foundation (models, types, interfaces)
2. Core logic (business rules)
3. Integration (connecting pieces)
4. Polish (error handling, edge cases)

Reference Pattern

In issue descriptions:

## Dependencies
- Depends on #12 (user model)
- Depends on #13 (API setup)

After creating issues, formally link dependencies:

tea issues deps add <issue> <blocker>
tea issues deps add 14 12    # Issue #14 depends on #12
tea issues deps add 14 13    # Issue #14 depends on #13

Creating Issues

Use the gitea skill for issue operations.

Single Issue

Create with a descriptive title and structured body:

• Summary section
• Acceptance criteria (testable checkboxes)
• Dependencies section referencing blocking issues

Batch Creation

When creating multiple related issues:

1. Plan all issues first
2. Create in dependency order
3. Update earlier issues with forward references

Roadmap View

To see current roadmap:

1. List open issues using the gitea skill
2. Group by labels/milestones
3. Identify blocked vs ready issues
4. Prioritize based on dependencies and value

Planning Questions

Before creating issues, answer:

• "What's the minimum viable version?"
• "What can we defer?"
• "What are the riskiest parts?"
• "How will we validate each piece?"