architecture/old/skills/roadmap-planning/SKILL.md

name, model, description, user-invocable

name	model	description	user-invocable
roadmap-planning	haiku	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. Discovery Phase

Before breaking down work into issues, understand the user's workflow:

Question	Why It Matters
Who is the user?	Specific persona, not "users"
What's their goal?	The job they're trying to accomplish
What's their workflow?	Step-by-step actions to reach the goal
What exists today?	Current state and gaps
What's the MVP?	Minimum to deliver value

Walk through the workflow step by step:

1. User starts at: [starting point]
2. User does: [action 1]
3. System responds: [what happens]
4. User does: [action 2]
5. ... continue until goal is reached

Identify the gaps:

• Where does the workflow break today?
• Which steps are missing or painful?
• What's the smallest change that unblocks value?

Derive issues from workflow gaps - not from guessing what might be needed. Each issue should address a specific gap in the user's workflow.

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

4. Identify Dependencies

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

5. 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?"