Purpose
Move the historical execution details of completed milestones out of the active path and generate a concise snapshot summary, to prevent historical documents from continuously polluting the AI's judgment of the current project state.
Core Objective
Primary Objective: Generate a snapshot summary for the completed milestone, collapse the historical roadmap section, and move the original task directory to _archive/。
Success Criteria(all must be satisfied when apply=true):
- ✅ Already generated at
milestones/_archive/{slug}-summary.mdsnapshot summary generated - ✅ The summary contains: completion date / key deliverables (≤5 items) / remaining gaps (pointing to subsequent milestones) / key ADR references
- ✅
roadmap.mdThe corresponding phase has been collapsed to a ≤ 3-line reference - ✅ Repo-wide grep of the old tasks.md path has been redirected to the summary
- ✅
milestones/{slug}/The directory has been removed (key information has been retained in the summary)
Acceptance Test: After execution, the AI reads milestones/_archive/m3-summary.md and can accurately understand the key results of m3 without needing to read the original tasks.md.
Maturity Determination
Archiving is allowed if any one of the following is satisfied; if none are satisfied, the skill refuses to execute and explains the reason:
| Condition | Basis for Determination |
|---|---|
| ≥ 60 days since completion date | In tasks.md frontmatter, the completed_at field |
| Current in-progress milestone index ≥ slug + 2 | In roadmap.md, the in-progress numeric suffix of the milestone |
Both conditions must also simultaneously satisfy "all tasks status=done or ✅".
When maturity is not reached, output a diagnosis:里程碑 {slug} 尚不满足归档条件:{具体原因}。
Behavior
Phase 1: Maturity Check
Read milestones/{slug}/tasks.md, and verify the maturity conditions. If any condition is not satisfied, stop.
Phase 2: Summary Generation (always executed)
Extract from tasks.md :
- Completion Date:frontmatter
completed_ator the last task completion date - Key Deliverables: all
status=donetasks, grouped by acceptance evidence, distilled into ≤ 5 items - Remaining Gaps: any items marked as "deferred", "next iteration", or incomplete, together with the target milestone
- Key ADR References: the ADR numbers mentioned in tasks.md
Phase 3: Impact Analysis (always executed)
Detect:
roadmap.mdThe phase paragraphs in that need to be collapsed- All files repo-wide that reference
milestones/{slug}/tasks.mdfiles
Phase 4: Output (dry-run vs apply)
dry-run (apply=false, default):
Output a preview report without modifying any files:
=== dry-run 预览 ===
将生成:
docs/process-management/milestones/_archive/{slug}-summary.md
(摘要草稿如下)
将修改:
roadmap.md 第 N-M 行折叠为:
### {阶段名}(已完成 {日期})→ 详见 [milestones/_archive/{slug}-summary.md]
将删除:
docs/process-management/milestones/{slug}/({N} 个文件)
引用更新({K} 处):
{文件路径}:{行号} → 旧路径 → 新摘要路径
=== 无文件已修改 ===
apply=true:
Execute all operations according to the preview, and finally output an operation log.
Anti-Patterns
- ❌ Executing directly without a maturity check
- ❌ Modifying any files when apply=false
- ❌ Executing apply=true when the git working tree has uncommitted changes (you should commit first to save the current state)
- ❌ The summary omits remaining gaps (the debt of historical decisions must be passed on to subsequent milestones)
- ❌ Only generating the summary without collapsing roadmap.md (the two must be synchronized)
- ❌ Full-repository reference updates not completed before deleting the task directory
Self-check checklist
Before execution:
- At least one maturity condition is met
- Git working tree is clean (when apply=true)
- Summary template fields are complete (completion date / deliverables / gaps / ADR)
After execution (apply=true):
-
_archive/{slug}-summary.mdexists and content is complete - roadmap.md phase section has been collapsed to ≤ 3 lines
- Full-repository grep
milestones/{slug}/tasks.mdno results -
milestones/{slug}/directory does not exist
Examples
Example 1: Normal scenario — archive after M3 is completed
Input:
docs/process-management/milestones/m3/contains tasks.md completed for 60 days (all status=completed)roadmap.mdM3 phase marked ✅- Subsequent milestone M4 has started
Execution(dry-run by default):
- Maturity check: M3 completion date ≥ 60 days ✓, subsequent milestone index difference ≥ 1 ✓
- Generate snapshot
milestones/_archive/m3-summary.md: completion date, 5 key deliverables, key ADR references - Provide impact analysis: roadmap M3 section will be collapsed to 3 lines; current path
milestones/m3/will be deleted - Output dry-run report and wait for user confirmation
After Apply: roadmap.md M3 section collapsed,milestones/_archive/m3-summary.md generated,milestones/m3/ removed.
Example 2: Boundary scenario — milestone just completed but maturity is insufficient
Input: M5 completion date is only 14 days ago, M6 has not yet started.
Execution:
- Maturity check: completion date < 60 days and subsequent milestone index difference = 0
- Refuse execution: output "milestone is not yet mature (14 days < 60-day threshold; subsequent milestone has not started), recommend archiving after ≥60 days or after M6 starts"
- Do not generate a snapshot, do not modify roadmap
Result: retain M5 as is; the user can rerun after the conditions are met.