From milestone-driven
Close out a completed milestone by documenting results, noting discrepancies, adding manual testing/demo steps, and preparing PLAN.md for the next cycle. Trigger whenever the user says "close milestone", "milestone done", "wrap up", "close it out", "phase 4", "finish the milestone", "we're done", or when all tasks in PLAN.md are marked complete and the user wants to finalize. Also trigger when the user asks to document what was built, write demo steps, or prepare for the next planning cycle.
How this skill is triggered — by the user, by Claude, or both
Slash command
/milestone-driven:milestone-closingopusThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> For the full workflow this skill belongs to, see [workflow-overview.md](../_shared/workflow-overview.md).
For the full workflow this skill belongs to, see workflow-overview.md.
You are guiding the human through the Milestone Closing phase of an AI-native
milestone-driven workflow. Your job is to verify completeness, document the outcome, record
anything noteworthy, and reset PLAN.md for the next cycle.
PLAN.md exists with tasks — ideally all marked [x] (done) or [~] (postponed).ROADMAP.md exists with the relevant milestone marked in progress.Read PLAN.md and ROADMAP.md. Verify:
All tasks resolved. Every task should be [x] or [~]. If any are still [ ],
ask the human: "Task N is still open — should we implement it, postpone it, or drop
it before closing?"
Success criteria met. Read the milestone's success criteria from ROADMAP.md
(formatted as - [ ] checkboxes by strategic-planning). For each criterion, assess
whether the implemented tasks collectively satisfy it, then edit ROADMAP.md to
tick the box (- [ ] → - [x]) for every met criterion. Leave unmet criteria as
- [ ] and either flag them for discussion or annotate them inline (e.g.,
- [ ] <criterion> — descoped, see closing notes). Do not skip this edit: an
unticked criterion in a "completed" milestone is a documentation bug.
Postponed tasks. For each [~] task, confirm the postponement reason is documented
and ask whether it should become part of a future milestone.
If any tasks are unresolved or criteria are not fully met, discuss with the human before proceeding.
Once all tasks are resolved, write the closing content directly to the milestone entry
in ROADMAP.md. Do not compose it in chat first — the file is the artifact.
Update the milestone's status from in progress to completed and append:
**Status:** completed
**Completed:** <date>
**Closing Notes:**
- <Scope changes: tasks that grew, shrunk, split, or were added mid-milestone>
- <Architectural surprises: tech debt, unexpected coupling, performance issues>
- <Decision changes: original decisions revised during implementation, and why>
- <Postponed items summary: what was deferred and why>
### Manual Testing & Demo
**Prerequisites:**
- <Environment setup, seed data, config needed>
**Verification Steps:**
1. <Step to verify criterion 1>
- Expected: <what should happen>
2. <Step to verify criterion 2>
- Expected: <what should happen>
...
**Demo Script** (for stakeholder presentation):
1. <Start state>
2. <Action to show the new capability>
3. <Point out what changed / what's new>
After writing to ROADMAP.md, tell the human the closing notes are ready for review and
point them to the file. Apply any requested changes directly to ROADMAP.md — keep the
feedback loop on the file, not in chat.
Ask the human to walk through the verification steps and confirm everything works.
If verification surfaces deviations from the success criteria or missing pieces /
errors that block shippable user value, do not proceed to reset. Instead, add one or
more tasks to PLAN.md so the human can re-iterate via task-implementation:
milestone-breakdown produces (- [ ] <task>
with a brief description, file hints if known, and acceptance criteria).## Re-iteration: <milestone title> so they're
distinguishable from the original breakdown.task-implementation until
all new tasks are [x], then re-invoke milestone-closing, which restarts at Step 1.If in doubt, ask the human before adding tasks — small polish issues may be better folded into a patch commit, while genuine scope gaps belong in PLAN.md. Borderline cases (e.g., "is this a bug or a future enhancement?") should be surfaced explicitly rather than silently turned into tasks or silently ignored.
Only proceed to Step 5 once verification passes cleanly with no blocking deviations. Steps 5 and 6 must not run while deviation tasks are open — they only execute on a clean pass through Step 4.
With the milestone verified and closed, bring README.md up to date so it reflects the
project's current state. Read the existing README.md and reconcile it against what
was actually shipped in this milestone:
Keep edits scoped to what changed in this milestone — do not rewrite unrelated parts of the README. If the milestone produced no user-visible or developer-visible changes that warrant a README update, note that explicitly to the human and skip the edit.
Truncate PLAN.md to prepare for the next cycle. Replace its contents with:
# Plan
> Ready for next milestone breakdown.
> Last completed: <milestone title> (<date>)
This keeps a breadcrumb of what came before while making the file clean for the next breakdown phase.
Briefly note what was delivered and suggest the user commit using /commit, then:
Not all criteria met but human wants to close: This is fine — real projects have pragmatic scope cuts. Document what was descoped and why. Suggest creating a follow-up milestone for the remaining criteria if they're still important.
Human discovers a bug during manual testing:
Use Step 4's re-iteration path: add a task (or a small cluster of tasks) to PLAN.md
describing the bug and its acceptance criteria, then let task-implementation handle it
under TDD. For trivial polish (typos, copy tweaks), a direct patch is fine — but
anything that touches behavior covered by success criteria should go through a task so
it gets test coverage. If unsure whether something is a "bug now" vs. "future
enhancement", ask the human before deciding.
Postponed tasks need a home:
For each postponed task, help the human decide: does it belong in a future milestone?
Should it be tracked as tech debt? Or is it no longer relevant? Add appropriate notes
to ROADMAP.md.
PLAN.md should be empty and ready. No leftover state
bleeding into the next cycle.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub mtrense/skills --plugin milestone-driven