SuperAPI AI Directory

archive-milestone

General & other

View repository

Updated 10-15 23:47

About this skill

Skill: Archive Milestone

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):

  1. ✅ Already generated at milestones/_archive/{slug}-summary.md snapshot summary generated
  2. ✅ The summary contains: completion date / key deliverables (≤5 items) / remaining gaps (pointing to subsequent milestones) / key ADR references
  3. ✅ roadmap.md The corresponding phase has been collapsed to a ≤ 3-line reference
  4. ✅ Repo-wide grep of the old tasks.md path has been redirected to the summary
  5. ✅ 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_at or the last task completion date
  • Key Deliverables: all status=done tasks, 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.md The phase paragraphs in that need to be collapsed
  • All files repo-wide that reference milestones/{slug}/tasks.md files

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.md exists and content is complete
  • roadmap.md phase section has been collapsed to ≤ 3 lines
  • Full-repository grep milestones/{slug}/tasks.md no 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.md M3 phase marked ✅
  • Subsequent milestone M4 has started

Execution(dry-run by default):

  1. Maturity check: M3 completion date ≥ 60 days ✓, subsequent milestone index difference ≥ 1 ✓
  2. Generate snapshot milestones/_archive/m3-summary.md: completion date, 5 key deliverables, key ADR references
  3. Provide impact analysis: roadmap M3 section will be collapsed to 3 lines; current path milestones/m3/ will be deleted
  4. 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:

  1. Maturity check: completion date < 60 days and subsequent milestone index difference = 0
  2. 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"
  3. Do not generate a snapshot, do not modify roadmap

Result: retain M5 as is; the user can rerun after the conditions are met.