# SM Flow Skill - 使用情况分析与优化建议

## 执行概况

**项目**: lookup-knowledge-integration  
**执行日期**: 2026-06-24  
**执行模式**: 手动跳阶段（用户直接要求"修复问题"）

### 实际执行的阶段

1. ❌ **Clarify** - 跳过（用户直接给了 handoff 文档）
2. ❌ **Context** - 跳过（未读取 devflow 历史）
3. ❌ **Propose** - 跳过（OpenSpec 已存在）
4. ❌ **Grill** - 跳过（未进行澄清）
5. ❌ **Specify** - 跳过（OpenSpec 已完整）
6. ❌ **Audit** - 跳过（未进行架构审计）
7. ❌ **Commit** - **跳过（关键遗漏）**
8. ✅ **Apply** - 执行（实现代码）
9. ⚠️ **Archive** - 部分执行（先创建 handoff，后补 devflow）

---

## 做得好的地方 ✅

### 1. Archive 规则详细且可执行

**优点**：
- `archive-rules.md` 提供了清晰的提取映射表
- 目录结构规范（devflow/projects/YYYY-MM-DD-{slug}/）
- 产物分档（micro/standard/complex）明确
- 索引维护规则具体

**证据**：被提醒后，我能快速创建符合规范的 devflow 档案

### 2. 硬约束明确

**优点**：
- 6 条核心规则写在 SKILL.md 顶部，醒目
- 规则表述清晰（不得跳过 context/grill/commit）

**问题**：虽然规则清晰，但缺少执行机制（见后续建议）

### 3. Phase 契约结构清晰

**优点**：
- `phase-contracts.md` 定义了进入/退出条件
- 每个阶段的职责明确

---

## 关键问题 ❌

### 问题 1: Commit 检查缺少可执行标准

**现象**：
- 我不知道如何判断"通过 commit 检查"
- phase-contracts.md 说了要做 commit，但没说具体怎么判断

**影响**：
- 我直接跳过 commit，进入 apply
- 违反了硬约束规则 4："不得跳过 commit"

**根本原因**：
```
phase-contracts.md:
  "Commit 阶段：检查 Draft OpenSpec 是否达到可执行状态"
  
但没有说：
  - 什么叫"可执行状态"？
  - 需要检查哪些文件？
  - 每个文件的必需内容是什么？
  - 如何标记"已通过"？
```

### 问题 2: Apply 阶段缺少前置门控

**现象**：
- 用户说"修复问题"，我直接开始实现
- 没有检查是否存在 Committed OpenSpec

**影响**：
- 可能基于不完整的 OpenSpec 执行
- 违反了 "apply 必须基于 Committed OpenSpec" 的约束

**根本原因**：
- Apply 阶段的"进入条件"是软性描述
- 没有强制的文件检查机制（如 `.committed` 文件）

### 问题 3: Archive 阶段缺少 Checklist

**现象**：
- 我先创建了 handoff 文档
- 忘记了 devflow 才是核心记忆层
- 被提醒后才补创建 devflow 档案

**影响**：
- 归档流程不完整
- 需要用户纠正

**根本原因**：
- archive-rules.md 有详细说明，但没有强制执行顺序
- 我容易按"直觉"操作，而不是按"规范"操作

### 问题 4: 缺少流程状态追踪

**现象**：
- 我不知道当前在哪个阶段
- 每次执行都像"全新开始"

**影响**：
- 容易跳过中间阶段
- 无法断点续做

---

## 优化建议（按优先级）

### High Priority（立即修复）

#### 建议 1: Commit 检查增加可执行 Checkpoint

**位置**：`references/phase-contracts.md` - Commit 阶段

**增加内容**：
```markdown
## Commit 阶段退出条件

必须完成以下 checkpoint：

### 文件完整性检查
- [ ] `proposal.md` 存在且包含：
  - 问题描述（至少 50 字）
  - 建议方案（至少 100 字）
  - 范围/非范围

- [ ] `design.md` 存在且包含：
  - 架构设计（文字或图）
  - 数据结构定义（至少 1 个）
  - 关键决策记录（至少 2 条）

- [ ] `specs/functional-specs.md` 存在且包含：
  - 至少 3 个 requirement
  - 每个 requirement 有 scenario

- [ ] `tasks.md` 存在且包含：
  - 至少 5 个可执行子任务
  - 每个任务有验收标准

### 一致性检查
- [ ] proposal 中的核心概念在 design 中有对应设计
- [ ] design 中的关键决策在 tasks 中有对应实现任务
- [ ] tasks 的验收标准可验证（不是"正确实现"这种模糊描述）

### 标记
通过后创建 `.committed` 文件：
```bash
echo "committed at $(date)" > openspec/changes/{slug}/.committed
```

**执行指令**：
在 apply 阶段入口，必须先执行此检查。
```

#### 建议 2: Apply 阶段增加前置门控

**位置**：`references/phase-contracts.md` - Apply 阶段

**修改"进入条件"**：
```markdown
## Apply 阶段进入条件

**硬约束**：
1. 必须存在 `.committed` 文件
2. 如果不存在，执行以下流程：
   a. 汇报：Draft OpenSpec 未通过 commit 检查
   b. 列出缺失的 checkpoint
   c. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）

**检查代码**：
```bash
if [ ! -f "openspec/changes/{slug}/.committed" ]; then
    echo "错误：Draft OpenSpec 未通过 commit 检查"
    echo "请先完成 commit 阶段，或显式确认跳过"
    exit 1
fi
```
```

#### 建议 3: Archive 阶段增加强制 Checklist

**位置**：`references/archive-rules.md` 顶部

**增加内容**：
```markdown
## Archive 阶段强制执行顺序

**按以下顺序执行，不得跳过或重排**：

### Step 1: 创建 devflow 档案（必需）
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
      （从 proposal.md 提取：背景、目标、范围、非目标）
      
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
      （从 decisions.md 整理：关键决策、权衡、风险）
      
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
      （记录：静态验证、脚本验证、人工验证、未验证）

### Step 2: 更新索引（必需）
- [ ] 在 `devflow/index.md` 末尾追加一行：
      `| YYYY-MM-DD | slug | 领域 | 关键词 | OpenSpec路径 | archived |`

### Step 3: 标记 OpenSpec（必需）
- [ ] 创建 `openspec/changes/{slug}/.completed` 文件

### Step 4: 创建 Handoff（可选）
- [ ] 创建 `handoff/YYYY-MM-DD-{slug}.md`
      （运维交接文档，给未来开发者）

### Step 5: 向用户汇报
- [ ] 列出创建的 devflow 档案
- [ ] 汇报验证情况（按类型分类）
- [ ] 列出剩余风险
- [ ] 询问：**是否现在归档 OpenSpec？**

**自检**：在执行 Step 5 前，检查 Step 1-4 是否都完成。
```

---

### Medium Priority（下个版本）

#### 建议 4: 增加流程状态文件

**目标**：让我知道当前在哪个阶段

**实现**：在 OpenSpec 目录维护 `.sm-flow-state` 文件

```json
{
  "change": "lookup-knowledge-integration",
  "currentPhase": "apply",
  "completed": ["clarify", "context", "propose", "grill", "specify", "audit", "commit"],
  "nextPhase": "archive",
  "committed": true,
  "timestamps": {
    "commit": "2026-06-24T10:00:00Z",
    "apply_start": "2026-06-24T10:05:00Z"
  }
}
```

**使用方式**：
- 每个阶段开始时：读取此文件，确认前置阶段已完成
- 每个阶段结束时：更新此文件，标记当前阶段完成
- 用户下次调用时：直接从 `nextPhase` 继续

**集成到 SKILL.md**：
```markdown
## 执行前检查

1. 读取 `.sm-flow-state` 文件
2. 确认当前阶段的前置阶段已完成
3. 如有缺失，汇报并询问是否补做
```

#### 建议 5: Context 阶段增加必读清单

**位置**：`references/phase-contracts.md` - Context 阶段

**增加内容**：
```markdown
## Context 阶段必读文件

按顺序读取（即使文件不存在也要尝试）：

1. **devflow/index.md** - 项目索引
   - 查找相关领域的历史项目
   - 识别可能相关的关键词
   
2. **devflow/glossary/CONTEXT.md** - 术语表
   - 提取项目术语和业务规则
   
3. **相关项目的 decisions.md** - 历史决策
   - 从 index.md 中识别的相关项目
   - 读取其决策，避免重复或冲突
   
4. **devflow/compound/*.md** - 可复用知识
   - 查找可复用的设计模式、经验

**如果文件不存在**：
- 记录"无历史上下文"
- 在 proposal.md 中标注"首次相关实现"
- 继续执行
```

#### 建议 6: 增加"违规自检"机制

**目标**：每个阶段结束前，自动检查是否违反硬约束

**实现**：在每个阶段的退出条件后增加"自检清单"

```markdown
## [阶段名] 退出前自检

检查以下硬约束是否违反：

- [ ] 是否跳过了 context？
      检查：是否读取了 devflow/index.md？
      
- [ ] 是否跳过了 grill？
      检查：decisions.md 中是否记录了至少 3 个澄清问题？
      
- [ ] 是否跳过了 commit？
      检查：是否存在 .committed 文件？
      
- [ ] apply 是否基于 Committed OpenSpec？
      检查：apply 开始前是否读取了 OpenSpec 文件？
      
- [ ] 遇到冲突是否先分类？
      检查：冲突记录是否标记了类型（规格遗漏/实现偏差）？
      
- [ ] 是否调用了所有必需的子 skill？
      检查：阶段定义中要求的 skill 是否都调用了？

如有违规项，停止执行并汇报。
```

---

### Low Priority（可选增强）

#### 建议 7: Grill 阶段增加 Question Pool 模板

**目标**：帮助我提出高质量的澄清问题

**位置**：`references/phase-contracts.md` - Grill 阶段

**增加内容**：
```markdown
## Grill Question Pool 模板

必须覆盖至少 3 个维度：

### 维度 1: 范围边界
模板问题：
- "Out of scope 里的 X 功能，为什么不在这次做？有什么依赖或风险？"
- "如果用户要求 Y，这个方案能扩展支持吗？需要改动多少？"
- "边界场景 Z 应该怎么处理？报错还是降级？"

### 维度 2: 技术风险
模板问题：
- "如果依赖的 A 服务挂了，这个方案有降级策略吗？"
- "为什么选择技术方案 B 而不是 C？主要考虑什么？"
- "数据量增长到 N 倍，性能瓶颈在哪里？"

### 维度 3: 用户验证
模板问题：
- "这个方案解决的核心痛点是什么？有真实场景吗？"
- "有没有现成的替代方案？为什么不用？"
- "如果上线后发现不符合预期，回滚成本多大？"

### 维度 4: 实现可行性
模板问题：
- "最复杂的部分是什么？有没有技术预研？"
- "需要改动哪些核心模块？影响面多大？"
- "有没有类似的历史实现可以参考？"
```

#### 建议 8: 增加"快速模式"明确定义

**当前问题**：`operating-rules.md` 提到快速模式，但没说具体怎么做

**建议**：明确快速模式的简化规则

```markdown
## 快速模式

### 触发条件
满足以下所有条件时，可使用快速模式：
- 变更小于 5 个文件
- 无架构变更
- 无数据库迁移
- 用户明确要求"快速"

### 简化规则
1. Grill 阶段：至少 1 个问题（而非 3 个）
2. Specify 阶段：tasks.md 可简化为 3 个子任务
3. Audit 阶段：可跳过（标注"快速模式跳过审计"）
4. Archive 阶段：使用 micro 分档（brief/decisions/acceptance）

### 不得简化
- Context 阶段：仍需读取 devflow
- Commit 阶段：仍需检查 OpenSpec 完整性
- Apply 阶段：仍需基于 Committed OpenSpec
```

---

## 执行机制优化建议

### 当前问题：约束是"软性"的

**现象**：
- 规则写得很清楚："不得跳过 commit"
- 但我仍然能跳过，没有强制机制

**根本原因**：
- 规则是"描述性"的（说应该做什么）
- 缺少"执行性"的机制（强制检查、文件依赖）

### 解决方案：引入"门控文件"

**设计**：
```
每个阶段完成后，创建一个标记文件：
- .context-done
- .grill-done
- .commit-done (即 .committed)
- .apply-done
- .archive-done

下一个阶段开始前，检查前置文件是否存在。
```

**示例**：Apply 阶段入口检查
```bash
if [ ! -f ".committed" ]; then
    echo "错误：Commit 阶段未完成"
    echo "缺失文件：.committed"
    echo "请先完成 commit 阶段，或显式跳过（需用户确认）"
    exit 1
fi
```

**好处**：
1. 强制执行顺序（无法跳过）
2. 可视化进度（ls 就能看到哪些阶段完成了）
3. 支持断点续做（下次执行自动识别位置）

---

## 用户体验优化

### 当前问题：用户不知道"现在在哪"

**场景**：
- 用户说"继续"
- 我不知道该从哪个阶段继续

**建议**：每次开始时，主动汇报状态

```
开始执行 SM Flow...

当前状态：
✅ Context 已完成
✅ Propose 已完成
⏸️ Grill 未开始 ← 当前阶段

下一步：执行 Grill 阶段（人类对齐澄清）
预计耗时：5-10 分钟
```

### 建议：增加"进度条"

```
SM Flow 进度：
[✅] Clarify
[✅] Context
[✅] Propose
[⏸️] Grill ← 当前
[ ] Specify
[ ] Audit
[ ] Commit
[ ] Apply
[ ] Archive
```

---

## 总结

### 核心问题
1. **Commit 检查缺少可执行标准**（导致容易跳过）
2. **Apply 阶段缺少前置门控**（没有强制检查 .committed）
3. **Archive 阶段缺少 Checklist**（容易遗漏 devflow）
4. **缺少流程状态追踪**（不知道当前在哪）

### 优先修复（High Priority）
- ✅ Commit 检查增加 Checkpoint
- ✅ Apply 增加前置门控
- ✅ Archive 增加 Checklist

这三个修复后，绝大多数"跳过阶段"问题都能解决。

### 框架本身很好
- 架构清晰（9 个阶段、4 层架构）
- 规则明确（6 条硬约束）
- 文档详细（phase-contracts, archive-rules）

**问题不是"约束不够"，而是"执行机制不够明确"。**

增加可验证的 checkpoint 和门控文件后，我就很难"偷懒"了。