architecture/skills/milestone-planning/SKILL.md

---
name: milestone-planning
description: >
  Value-based milestone planning: milestones as shippable capabilities, not phases.
  One active milestone, vertical slices, value/risk labels. Use when planning
  milestones or organizing backlog by capability.
user-invocable: false
---

# Milestone Planning

Value-driven milestone framework: milestones represent shippable business capabilities, not time-based phases.

## Core Principle

**If you don't deliver by date, milestones must represent value slices, not time.**

**Milestone = A shippable business capability**

Not a phase. Not "MVP". Not "Auth".

## What Makes a Good Milestone

Each milestone should answer one business question:

**"What new capability exists for the user once this is done?"**

### Good Examples

✓ Customer can register and authenticate
✓ Order can be placed and paid
✓ Admin can manage products
✓ Audit trail exists for all state changes

### Bad Examples

✗ MVP (what capability?)
✗ Backend (technical layer, not user value)
✗ Auth improvements (vague, no completion criteria)
✗ Phase 1 (time-based, not value-based)

**Test:** If it can't be demoed independently, it's too vague.

## Mapping DDD Issues to Milestones

**DDD building blocks → issues**
- Aggregates
- Commands
- Events
- Read models
- Policies

**End-to-end capability → milestone**
- Spans multiple aggregates
- Commands + invariants + events
- Read models for visibility
- Maybe UI/API glue

**Value is cross-cutting by nature.**

A milestone usually includes:
- Multiple aggregates working together
- Commands that achieve user goal
- Events connecting aggregates
- Read models for user feedback
- UI/API to trigger capability

## One Active Milestone at a Time

**Rule:** Exactly one open milestone = current value focus

**Why:**
- Preserves focus
- Avoids parallel half-value
- Forces completion
- Makes priority explicit

**Practice:**
- Everything else stays unassigned
- When done → close it → pick next highest-value milestone
- Multiple open milestones = accidental roadmap

## Priority Without Dates

Since Gitea milestones have no ordering, use labels:

**Minimal label set:**
- `value/high` - Highest business value
- `value/medium` - Moderate business value
- `value/low` - Nice to have
- `risk/high` - Technical risk or uncertainty

**Issues have:**
- Always: value label
- Sometimes: risk label

**You now have:**
- **Milestone** → what capability
- **Label** → why now

## Sizing Guidelines

A value milestone should:
- Be completable in days to a few weeks
- Deliver observable user value
- Contain 5-25 issues

**If it keeps growing:**
- You discovered multiple capabilities
- Split into separate milestones

## Vertical Slice Test

Before creating a milestone, verify:

**Can this be demoed independently?**

Test questions:
- Can a user interact with this capability end-to-end?
- Does it produce observable results?
- Is it useful on its own (not just foundation)?
- Can we ship this and get feedback?

If NO to any → not a value slice yet.

## Label Strategy

**Value labels (always):**
- Reflect business priority
- Based on user impact, revenue, strategic alignment
- Applied to every issue in milestone

**Risk labels (optional):**
- Flag technical uncertainty
- Flag new patterns/technologies
- Flag complex integrations
- Helps sequence work (derisk early)

## Anti-Patterns

**"We just deliver highest value first"**
Only works if:
- Value is explicit (labels)
- Scope is bounded (milestones)
- Work is finishable (vertical slices)

Without milestones, "value-first" quietly becomes "interesting-first".

**Multiple open milestones:**
- Splits focus
- Encourages context switching
- Hides incomplete work
- Prevents shipping

**Technical milestones:**
- "Backend" is not a capability
- "API layer" is not demoable
- "Database migration" might be necessary but not a milestone

**Phase-based milestones:**
- "MVP" → what can user do?
- "Phase 1" → what capability?
- "Q1 goals" → what ships?

## When NOT to Use Milestones

**Don't use milestones when:**
- Single capability with <5 issues (just label it)
- Exploratory work (use spike label instead)
- Refactoring without user-visible change (use technical debt label)
- Everything ships together (waterfall project)

**Milestones enforce discipline around value slices.**

## Workflow Summary

1. **Issues exist** (from DDD analysis or backlog)
2. **Group by capability** (milestone-planner agent)
3. **One milestone open** (current value slice)
4. **Label for priority** (value/risk)
5. **No dates** (capability-based, not time-based)
6. **Close ruthlessly** (finish before starting next)

## Tips

- Start with 3-5 milestones defined, 1 active
- Keep unassigned issues in backlog
- Move issues between milestones if capability boundaries change
- Split milestones that grow beyond 25 issues
- Close milestone when capability is demoable
- Review value/risk labels regularly
- Active milestone = team's current focus