git-learn/.agents/skills/sm-flow/references/fallbacks.md

Fallback 协议

当子 skill 无法直接调用时使用这些协议。Fallback 不是绕过 OpenSpec 的许可；v3 中 fallback 的目标仍然是生成、修正或执行 OpenSpec 产物。使用任何 fallback 前必须先向用户说明：目标子 skill、无法调用原因、降级协议名称、降级风险。产物中也必须记录“本阶段为 fallback 降级执行”。

Fallback 记录要求

任何 fallback 都必须同时满足以下记录要求：

1. 在对用户的阶段汇报里声明：
   • 目标 capability
   • 不可用原因
   • 使用的 fallback 协议名
   • 本次降级风险
2. 在 decisions.md、evidence.md 或 acceptance.md 中留下同样的降级记录。
3. 如果当前阶段需要 checkpoint，则 fallback 声明是 checkpoint 完成条件的一部分。
4. 如果没有完成这些声明和记录，该阶段不得视为已完成。

除非某个 fallback 额外说明，否则下面各节默认继承这组通用记录要求，不再重复要求“记录本阶段 fallback 声明”。

OpenSpec 提案 fallback

1. 创建或识别 openspec/changes/{slug}/。
2. 先读取 devflow 上下文：devflow/glossary/CONTEXT.md、相关项目档案、ADR、acceptance、compound knowledge。
3. 写入 proposal.md，包含：
   • 问题
   • 建议方案
   • 范围
   • 非目标
   • 来自 devflow 的上下文约束
   • 风险
4. 当实现需要技术选择时，写入 design.md，并引用相关 ADR 或历史验收结论。
5. 将 tasks.md 写成按纵向切片组织的 checkbox 清单。
6. 只为外部可见行为或发生变化的需求编写 specs。
7. 如果存在高风险假设，在 Phase 1.5 前向用户 checkpoint。

OpenSpec 修正 fallback

当 PRD、devflow、澄清结论、架构审计和 OpenSpec 冲突时：

1. 列出冲突来源：PRD / glossary / ADR / acceptance / compound / OpenSpec。
2. 判断冲突类型：术语、范围、验收、架构、任务拆分、风险。
3. 向用户汇报冲突和推荐修正。
4. 用户确认后，优先修正 OpenSpec proposal/design/specs/tasks。
5. 再同步更新 devflow 文档；不要只改 devflow。
6. 额外记录冲突修正状态。

OpenSpec 执行 fallback

仅当 openspec-apply-change 不可调用时使用。执行依据仍必须是 openspec/changes/{slug}/。

1. 阅读 proposal.md、design.md、specs/**/*.md 和 tasks.md。
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
5. 修改前先检查现有代码。
6. 一次实现一个 OpenSpec task 的纵向切片。
7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
   • 实现偏差：OpenSpec 正确，代码偏离；修代码。
   • 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
   • 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
   • 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 decisions.md 或 acceptance.md。
9. 用最窄但有效的命令验证每个切片。
10. 只有验证通过或明确记录原因后，才更新 task 状态。
11. 如果失败原因不确定，停止并进入 diagnose。
12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
13. 额外记录任务推进状态和验证状态。

PRD fallback

优先使用 references/templates.md#brief-模板 创建 brief.md。只有复杂需求、对外协作或用户明确要求 PRD 时，才使用 references/templates.md#prd-模板 创建 prd.md。

规则：

• 从当前上下文、devflow 记忆和 OpenSpec 产物综合，不要机械复制。
• brief.md 或 PRD 用来表达用户价值、范围和验收口径；不能替代 OpenSpec specs/tasks。
• 只有当缺失决策会阻塞 OpenSpec 正确性时，才采访用户。
• 额外记录是否创建了独立 prd.md。

文档化追问 fallback

1. 阅读已有词汇表、ADR、相关 OpenSpec 产物和 devflow 项目档案。
2. 先声明每个问题的模式：evidence-driven 或 user-interview。
3. 对 evidence-driven 问题，先查代码库、文档、OpenSpec 或 ADR，再向用户汇报证据和结论。
4. 对 user-interview 问题，一次只问一个并等待用户确认。
5. 术语确认后立即更新词汇表。
6. 影响实现的澄清必须回写 OpenSpec。
7. 只为难以逆转的真实权衡创建 ADR。
8. 额外记录 question pool 和已消费问题。

快速模式的最小问题：

• 术语：这个概念应该使用哪个领域术语？证据是什么？
• 边界：哪些内容明确不在范围内？是否需要用户确认？
• 验收：什么可观察行为能证明它完成？是否已写入 OpenSpec specs？

架构审计 fallback

产出一份短架构审计：

1. 画出输入 → 处理 → 输出。
2. 列出相关模块和调用方。
3. 识别耦合、数据所有权和生命周期风险。
4. 检查是否与词汇表、ADR 和 OpenSpec design 冲突。
5. 用不超过五句话总结最大风险。
6. 如果影响实现，回写 OpenSpec design/tasks。
7. 额外记录审计结论回写状态。

Diagnose fallback

1. 复现问题，或捕获准确失败信息。
2. 最小化失败案例。
3. 生成 3-5 个假设，并按可能性和验证成本排序。
4. 修改代码前，先添加仪器化或定向检查。
5. 判断根因属于实现问题还是 OpenSpec 规格问题。
6. 如果是实现问题，修复被证明的最小原因。
7. 如果是规格问题，先修正 OpenSpec，再继续 apply。
8. 运行回归验证。
9. 额外记录根因分类和回归结果。

TDD fallback

使用纵向切片，不要水平批量写测试：

1. 从 OpenSpec specs 中选择一个外部可见行为。
2. 写一个失败测试。
3. 实现刚好让测试通过的最小代码。
4. 只在测试通过时重构。
5. 对下一个 OpenSpec 行为重复以上步骤。
6. 额外记录当前行为切片的测试状态。