architecture/skills/roadmap-planning/SKILL.md

---
name: roadmap-planning
description: 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.
user-invocable: 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:
```markdown
## Dependencies
- Depends on #12 (user model)
- Depends on #13 (API setup)
```

After creating issues, formally link dependencies:
```bash
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?"