Archive Milestone

Skill: Archive Milestone

Purpose

Move the historical execution detail of a completed milestone out of the active paths and produce a lean snapshot summary, so old documents stop clouding the AI's read of the project's current state.

Core Objective

Primary goal: produce a snapshot summary for a completed milestone, fold the historical roadmap section, and move the original tasks directory into _archive/.

Success criteria (with apply=true, all of them must hold):

1. ✅ The snapshot summary was produced at milestones/_archive/{slug}-summary.md
2. ✅ The summary carries: completion date / key deliverables (≤5 items) / leftover gaps (pointing at later milestones) / key ADR references
3. ✅ The matching stage in roadmap.md was folded into a reference of ≤ 3 lines
4. ✅ Every repository-wide grep hit on the old tasks.md path was redirected to the summary
5. ✅ The milestones/{slug}/ directory was removed (its key information is held in the summary)

Acceptance test: afterwards, an AI reading milestones/_archive/m3-summary.md understands the key outcomes of m3 accurately, without reading the original tasks.md.

Maturity Test

Any one of the following is enough to archive; when none of them holds, the skill refuses to run and explains why:

For both conditions, "every task is status=done or ✅" is also required.

When maturity is not reached, emit the diagnostic Milestone {slug} does not yet meet the archiving conditions: {specific reason}.

Behavior

Stage 1: maturity check

Read milestones/{slug}/tasks.md and verify the maturity conditions. Stop when no condition is met.

Stage 2: summary generation (always runs)

Extract from tasks.md:

• Completion date: the frontmatter completed_at, or the completion date of the last task
• Key deliverables: every status=done task, grouped by acceptance evidence, distilled into ≤ 5 items
• Leftover gaps: any entry marked "deferred" or "next iteration", or left unfinished, together with its target milestone
• Key ADR references: the ADR numbers mentioned in tasks.md

Stage 3: impact analysis (always runs)

Detect:

• The stage sections in roadmap.md that need folding
• Every file in the repository that references milestones/{slug}/tasks.md

Stage 4: output (dry-run vs apply)

dry-run (apply=false, the default):

Emit a preview report, changing no file:

=== dry-run preview ===

Will create:
  docs/process-management/milestones/_archive/{slug}-summary.md
  (draft summary below)

Will modify:
  roadmap.md lines N-M folded into:
    ### {stage name} (completed {date}) → see [milestones/_archive/{slug}-summary.md]

Will delete:
  docs/process-management/milestones/{slug}/ ({N} files)

Reference updates ({K} sites):
  {file path}:{line} → old path → new summary path

=== no file was modified ===

apply=true:

Perform every operation as previewed, then emit the operation log.

Anti-Patterns

• ❌ Running straight through without the maturity check
• ❌ Modifying any file while apply=false
• ❌ Running apply=true while the git working tree holds uncommitted changes (commit first to preserve the state)
• ❌ A summary that omits the leftover gaps (the debt of a past decision must carry over into later milestones)
• ❌ Producing the summary without folding roadmap.md (the two must stay in step)
• ❌ Deleting the tasks directory before the repository-wide reference update is finished

Self-Check

Before running:

• At least one maturity condition holds
• The git working tree is clean (when apply=true)
• The summary template fields are complete (completion date / deliverables / gaps / ADR)

After running (apply=true):

• _archive/{slug}-summary.md exists and its content is complete
• The roadmap.md stage section was folded into ≤ 3 lines
• A repository-wide grep for milestones/{slug}/tasks.md returns nothing
• The milestones/{slug}/ directory does not exist

Examples

Example 1: the normal case — archiving after M3 completes

Input:

• docs/process-management/milestones/m3/ holds a tasks.md completed 60 days ago (all status=completed)
• The M3 stage in roadmap.md is marked ✅
• The next milestone, M4, has started

Execution (dry-run by default):

1. Maturity check: M3 completed ≥ 60 days ago ✓ — one condition is enough, so the index condition (in-progress ≥ M5, currently M4) does not also have to hold
2. Produce the snapshot milestones/_archive/m3-summary.md: completion date, 5 key deliverables, key ADR references
3. Give the impact analysis: the roadmap M3 section will fold into 3 lines; the current path milestones/m3/ will be deleted
4. Emit the dry-run report and wait for the user to confirm

After apply: the roadmap.md M3 section is folded, milestones/_archive/m3-summary.md is produced, and milestones/m3/ is removed.

Example 2: edge case — the milestone just completed and is not mature enough

Input: M5 completed only 14 days ago, and the in-progress milestone is still M5, so neither condition holds.

Execution:

1. Maturity check: completion is < 60 days ago and the later milestone index differs by 0
2. Refuse to run: emit "the milestone is not mature yet (14 days < the 60-day threshold; no later milestone has started); suggest archiving after ≥60 days, or once M6 starts"
3. Produce no snapshot and change no roadmap

Result: M5 stays as it is; the user can rerun once the conditions are met.