architecture/skills/roadmap-planning/SKILL.md

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

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)

Creating Issues with fj

Single Issue

fj issue create "Add user authentication endpoint" --body "$(cat <<'EOF'
## Summary
Create POST /api/auth/login endpoint for user authentication.

## Acceptance Criteria
- [ ] Endpoint accepts email and password
- [ ] Returns JWT token on success
- [ ] Returns 401 on invalid credentials
- [ ] Rate limits login attempts

## Dependencies
- Depends on #5 (user model)
EOF
)"

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: fj issue search -s open
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?"