Back to Details

kata-plan-milestone-gaps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> Create all phases necessary to close gaps identified by `/kata-audit-milestone`.
Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
One command creates all fix phases — no manual 
/kata-add-phase
per gap. </objective>
<execution_context>
<!-- Spawns kata-planner agent which has all planning expertise baked in -->
</execution_context>
<context> **Audit results:** Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent)
Original intent (for prioritization): @.planning/PROJECT.md @.planning/REQUIREMENTS.md
Current state: @.planning/ROADMAP.md @.planning/STATE.md </context>
<process>
<objective> 创建所有必要的阶段，以解决`/kata-audit-milestone`识别出的差距。
读取MILESTONE-AUDIT.md，将差距按逻辑分组为不同阶段，在ROADMAP.md中创建阶段条目，并提供每个阶段的规划选项。
只需一条命令即可创建所有修复阶段——无需为每个差距手动执行
/kata-add-phase
。 </objective>
<execution_context>
<!-- 启动kata-planner agent，该agent内置了所有规划专业能力 -->
</execution_context>
<context> **审计结果：** 通配符：.planning/v*-MILESTONE-AUDIT.md（使用最新版本）
原始意图（用于优先级排序）： @.planning/PROJECT.md @.planning/REQUIREMENTS.md
当前状态： @.planning/ROADMAP.md @.planning/STATE.md </context>
<process>

1. Load Audit Results

1. 加载审计结果

bash
undefined
bash
undefined

Find the most recent audit file

查找最新的审计文件

find .planning -maxdepth 1 -name "v*-MILESTONE-AUDIT.md" 2>/dev/null | head -1

Parse YAML frontmatter to extract structured gaps:
- `gaps.requirements` — unsatisfied requirements
- `gaps.integration` — missing cross-phase connections
- `gaps.flows` — broken E2E flows

If no audit file exists or has no gaps, error:
No audit gaps found. Run 
/kata-audit-milestone
first.
undefined
find .planning -maxdepth 1 -name "v*-MILESTONE-AUDIT.md" 2>/dev/null | head -1

解析YAML前置元数据以提取结构化差距：
- `gaps.requirements` — 未满足的需求
- `gaps.integration` — 缺失的跨阶段连接
- `gaps.flows` — 损坏的端到端流程

如果不存在审计文件或文件中没有差距，返回错误：
未找到审计差距。请先运行
/kata-audit-milestone
。
undefined

2. Prioritize Gaps

2. 为差距划分优先级

Group gaps by priority from REQUIREMENTS.md:
PriorityAction
must
Create phase, blocks milestone
should
Create phase, recommended
nice
Ask user: include or defer?
For integration/flow gaps, infer priority from affected requirements.
根据REQUIREMENTS.md中的优先级对差距进行分组：
优先级操作
must
创建阶段，会阻碍里程碑达成
should
创建阶段，建议执行
nice
询问用户：包含还是推迟？
对于集成/流程差距，从受影响的需求推断优先级。

3. Group Gaps into Phases

3. 将差距分组为阶段

Cluster related gaps into logical phases:
Grouping rules:
  • Same affected phase → combine into one fix phase
  • Same subsystem (auth, API, UI) → combine
  • Dependency order (fix stubs before wiring)
  • Keep phases focused: 2-4 tasks each
Example grouping:
Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
Gap: Integration Phase 1→3 (Auth not passed to API calls)
Gap: Flow "View dashboard" broken at data fetch

→ Phase 6: "Wire Dashboard to API"
  - Add fetch to Dashboard.tsx
  - Include auth header in fetch
  - Handle response, update state
  - Render user data
将相关差距聚类为逻辑阶段：
分组规则：
  • 影响同一阶段 → 合并为一个修复阶段
  • 属于同一子系统（认证、API、UI）→ 合并
  • 按依赖顺序（先修复存根再进行连接）
  • 保持阶段聚焦：每个阶段包含2-4个任务
分组示例：
差距：DASH-01未满足（仪表板未获取数据）
差距：集成阶段1→3（认证信息未传递到API调用）
差距：“查看仪表板”流程在数据获取环节中断

→ 阶段6：“连接仪表板与API”
  - 为Dashboard.tsx添加数据获取逻辑
  - 在请求中包含认证头
  - 处理响应并更新状态
  - 渲染用户数据

4. Determine Phase Numbers

4. 确定阶段编号

Find highest existing phase:
bash
undefined
查找当前最高阶段编号：
bash
undefined

Scan all phase directories across states

扫描所有状态下的阶段目录

ALL_PHASE_DIRS="" for state in active pending completed; do [ -d ".planning/phases/${state}" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} $(find .planning/phases/${state} -maxdepth 1 -type d -not -name "${state}" 2>/dev/null)" done
ALL_PHASE_DIRS="" for state in active pending completed; do [ -d ".planning/phases/${state}" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} $(find .planning/phases/${state} -maxdepth 1 -type d -not -name "${state}" 2>/dev/null)" done

Fallback: include flat directories (backward compatibility)

兼容处理：包含扁平目录（向后兼容）

FLAT_DIRS=$(find .planning/phases -maxdepth 1 -type d -name "[0-9]*" 2>/dev/null) [ -n "$FLAT_DIRS" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} ${FLAT_DIRS}" echo "$ALL_PHASE_DIRS" | tr ' ' '\n' | sort -V | tail -1

New phases continue from there:
- If Phase 5 is highest, gaps become Phase 6, 7, 8...
FLAT_DIRS=$(find .planning/phases -maxdepth 1 -type d -name "[0-9]*" 2>/dev/null) [ -n "$FLAT_DIRS" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} ${FLAT_DIRS}" echo "$ALL_PHASE_DIRS" | tr ' ' '\n' | sort -V | tail -1

新阶段从该编号开始依次递增：
- 如果当前最高阶段是5，那么新差距对应的阶段为6、7、8...

5. Present Gap Closure Plan

5. 展示差距修复计划

markdown
undefined
markdown
undefined

Gap Closure Plan

差距修复计划

Milestone: {version} Gaps to close: {N} requirements, {M} integration, {K} flows
里程碑： {版本号} 待解决差距： {N}项需求差距，{M}项集成差距，{K}项流程差距

Proposed Phases

拟议阶段

Phase {N}: {Name} Closes:
  • {REQ-ID}: {description}
  • Integration: {from} → {to} Tasks: {count}
Phase {N+1}: {Name} Closes:
  • {REQ-ID}: {description}
  • Flow: {flow name} Tasks: {count}
{If nice-to-have gaps exist:}
阶段{N}：{名称} 解决以下差距：
  • {REQ-ID}：{描述}
  • 集成：{来源阶段} → {目标阶段} 任务数量：{count}
阶段{N+1}：{名称} 解决以下差距：
  • {REQ-ID}：{描述}
  • 流程：{流程名称} 任务数量：{count}
{如果存在nice-to-have类差距：}

Deferred (nice-to-have)

推迟项（nice-to-have）

These gaps are optional. Include them?
  • {gap description}
  • {gap description}
Create these {X} phases? (yes / adjust / defer all optional)

Wait for user confirmation.
这些差距为可选项。是否包含它们？
  • {差距描述}
  • {差距描述}
是否创建这{X}个阶段？（是/调整/推迟所有可选项）

等待用户确认。

6. Update ROADMAP.md

6. 更新ROADMAP.md

Add new phases to current milestone:
markdown
undefined
在当前里程碑中添加新阶段：
markdown
undefined

Phase {N}: {Name}

阶段{N}：{名称}

Goal: {derived from gaps being closed} Requirements: {REQ-IDs being satisfied} Gap Closure: Closes gaps from audit
目标： {从待解决差距推导} 需求： {待满足的REQ-ID} 差距修复： 解决审计中发现的差距

Phase {N+1}: {Name}

阶段{N+1}：{名称}

...
undefined
...
undefined

7. Create Phase Directories

7. 创建阶段目录

bash
undefined
bash
undefined

New gap closure phases go into pending/ subdirectory

新的差距修复阶段放入pending/子目录

mkdir -p ".planning/phases/pending/{NN}-{name}"
undefined
mkdir -p ".planning/phases/pending/{NN}-{name}"
undefined

8. Commit Roadmap Update

8. 提交路线图更新

Check planning config:
bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
If 
COMMIT_PLANNING_DOCS=false
: Skip git operations
If 
COMMIT_PLANNING_DOCS=true
(default):
bash
git add .planning/ROADMAP.md
git commit -m "docs(roadmap): add gap closure phases {N}-{M}"
检查规划配置：
bash
COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
如果
COMMIT_PLANNING_DOCS=false
： 跳过Git操作
如果
COMMIT_PLANNING_DOCS=true
（默认值）：
bash
git add .planning/ROADMAP.md
git commit -m "docs(roadmap): add gap closure phases {N}-{M}"

9. Offer Next Steps

9. 提供后续步骤建议

markdown
undefined
markdown
undefined

✓ Gap Closure Phases Created

✓ 差距修复阶段已创建

Phases added: {N} - {M} Gaps addressed: {count} requirements, {count} integration, {count} flows
已添加阶段： {N} - {M} 已处理差距： {count}项需求差距，{count}项集成差距，{count}项流程差距

▶ Next Up

▶ 下一步

Plan first gap closure phase
/kata-plan-phase {N}
<sub>
/clear
first → fresh context window</sub>
Also available:
  • /kata-execute-phase {N}
    — if plans already exist
  • cat .planning/ROADMAP.md
    — see updated roadmap
After all gap phases complete:
/kata-audit-milestone
— re-audit to verify gaps closed 
/kata-complete-milestone {version}
— archive when audit passes

</process>

<gap_to_phase_mapping>
规划首个差距修复阶段
/kata-plan-phase {N}
<sub>先执行
/clear
→ 刷新上下文窗口</sub>
其他可用操作：
  • /kata-execute-phase {N}
    — 若阶段规划已存在
  • cat .planning/ROADMAP.md
    — 查看更新后的路线图
所有差距修复阶段完成后：
/kata-audit-milestone
— 重新审计以验证差距已解决 
/kata-complete-milestone {version}
— 审计通过后归档里程碑

</process>

<gap_to_phase_mapping>

How Gaps Become Tasks

差距如何转化为任务

Requirement gap → Tasks:
yaml
gap:
  id: DASH-01
  description: "User sees their data"
  reason: "Dashboard exists but doesn't fetch from API"
  missing:
    - "useEffect with fetch to /api/user/data"
    - "State for user data"
    - "Render user data in JSX"

becomes:

phase: "Wire Dashboard Data"
tasks:
  - name: "Add data fetching"
    files: [src/components/Dashboard.tsx]
    action: "Add useEffect that fetches /api/user/data on mount"

  - name: "Add state management"
    files: [src/components/Dashboard.tsx]
    action: "Add useState for userData, loading, error states"

  - name: "Render user data"
    files: [src/components/Dashboard.tsx]
    action: "Replace placeholder with userData.map rendering"
Integration gap → Tasks:
yaml
gap:
  from_phase: 1
  to_phase: 3
  connection: "Auth token → API calls"
  reason: "Dashboard API calls don't include auth header"
  missing:
    - "Auth header in fetch calls"
    - "Token refresh on 401"

becomes:

phase: "Add Auth to Dashboard API Calls"
tasks:
  - name: "Add auth header to fetches"
    files: [src/components/Dashboard.tsx, src/lib/api.ts]
    action: "Include Authorization header with token in all API calls"

  - name: "Handle 401 responses"
    files: [src/lib/api.ts]
    action: "Add interceptor to refresh token or redirect to login on 401"
Flow gap → Tasks:
yaml
gap:
  name: "User views dashboard after login"
  broken_at: "Dashboard data load"
  reason: "No fetch call"
  missing:
    - "Fetch user data on mount"
    - "Display loading state"
    - "Render user data"

becomes:
需求差距 → 任务：
yaml
gap:
  id: DASH-01
  description: "用户可查看自己的数据"
  reason: "仪表板已存在但未从API获取数据"
  missing:
    - "使用useEffect调用/api/user/data接口"
    - "用户数据状态管理"
    - "在JSX中渲染用户数据"

转化为：

phase: "连接仪表板数据"
tasks:
  - name: "添加数据获取逻辑"
    files: [src/components/Dashboard.tsx]
    action: "添加useEffect，在组件挂载时调用/api/user/data接口"

  - name: "添加状态管理"
    files: [src/components/Dashboard.tsx]
    action: "为userData、loading、error状态添加useState"

  - name: "渲染用户数据"
    files: [src/components/Dashboard.tsx]
    action: "替换占位符，使用userData.map进行渲染"
集成差距 → 任务：
yaml
gap:
  from_phase: 1
  to_phase: 3
  connection: "认证令牌 → API调用"
  reason: "仪表板API调用未包含认证头"
  missing:
    - "在请求中添加认证头"
    - "401错误时刷新令牌"

转化为：

phase: "为仪表板API调用添加认证"
tasks:
  - name: "为请求添加认证头"
    files: [src/components/Dashboard.tsx, src/lib/api.ts]
    action: "在所有API调用中包含带令牌的Authorization头"

  - name: "处理401响应"
    files: [src/lib/api.ts]
    action: "添加拦截器，在收到401时刷新令牌或重定向到登录页"
流程差距 → 任务：
yaml
gap:
  name: "用户登录后查看仪表板"
  broken_at: "仪表板数据加载环节"
  reason: "未执行请求调用"
  missing:
    - "组件挂载时获取用户数据"
    - "显示加载状态"
    - "渲染用户数据"

转化为：

Usually same phase as requirement/integration gap

通常与需求/集成差距属于同一阶段

Flow gaps often overlap with other gap types

流程差距通常与其他类型的差距重叠


</gap_to_phase_mapping>

<success_criteria>
- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
- [ ] Gaps prioritized (must/should/nice)
- [ ] Gaps grouped into logical phases
- [ ] User confirmed phase plan
- [ ] ROADMAP.md updated with new phases
- [ ] Phase directories created
- [ ] Changes committed
- [ ] User knows to run `/kata-plan-phase` next
</success_criteria>

</gap_to_phase_mapping>

<success_criteria>
- [ ] 已加载MILESTONE-AUDIT.md并解析差距
- [ ] 已为差距划分优先级（must/should/nice）
- [ ] 已将差距分组为逻辑阶段
- [ ] 用户已确认阶段计划
- [ ] 已使用新阶段更新ROADMAP.md
- [ ] 已创建阶段目录
- [ ] 已提交变更
- [ ] 用户知晓下一步需运行`/kata-plan-phase`
</success_criteria>