architecture/skills/milestone-planning/SKILL.md

name, description, user-invocable

name	description	user-invocable
milestone-planning	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.	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