harness-plan

name	harness-plan
description	用 harness-core 模板为新任务生成 8 大区 spec 骨架并引导填写。触发：用户说 /harness-plan <task> 或 "为 X 写 spec"。

harness-plan skill

为任务写 harness spec（8 大区 + complexity）。

何时触发

• 用户显式 /harness-plan <task-name>
• 用户说"开始新任务之前先写 spec" / "给 X 写 spec"
• 用户提出一个需求但没写 spec 文档

前置判断（关键）

先判断当前会话是否已经讨论过此任务：

• 已讨论 → 进入"起草模式"：用对话内容直接起草 8 段草稿，给用户过目、逐段微调。不要从零开始问问题。
• 未讨论 / 讨论零散 → 进入"引导模式"：逐段问封闭问题帮用户填。

判断依据：翻一下当前 context 里是否已经出现过任务目标、涉及文件、约束条件等信息。只要有 2 段以上相关内容就算"已讨论"。

起草模式流程

1. 运行 harness plan new "<task-name>" 生成骨架，记录输出路径。
2. 基于会话内容直接起草 8 段 + complexity 字段，一次性给用户看完整草稿：

   ## Objective
   [从讨论中提炼的目标]
   
   ## User Flow
   [逐步用户动线：1. 用户在 X 页点 Y → 2. 看到 Z → 3. ...]
   
   ## Commands
   ...（以此类推 8 段，最后一段 Data Migration）
   
   complexity: simple | complex
   

3. 逐段问：「这段对吗？有要改的吗？」允许用户一次指出多处。
4. 用户确认一段就写入文件，不要等全部确认完才写（防中断丢内容）。
5. 全部确认后运行 harness plan validate <path>，不过就修。
6. 告诉用户：/harness-execute <path>。

引导模式流程（讨论不足时）

1. 运行 harness plan new "<task-name>"。
2. 按 8 大区逐个问封闭问题（"目标用户是谁？"而不是"介绍一下这个任务"）：
   • Objective：一句话目标 + 可验证的成功标准
   • User Flow：逐步用户动线（上传 → 看到什么 → 点什么 → 结果）。UI 相关任务必填；纯后端/工具类可写 "N/A - 无用户交互"。 必须问次要生命周期（主 AI 主动追问，不要等用户提）：
     1. 用户中途退出怎么办？需不需要"继续未完成的"功能？
     2. 历史记录可见吗？孩子能看到自己之前的 / 家长能看到孩子的？
     3. 异常恢复？（网络断、重启） 多阶段 / 多步骤流程必须明确每个阶段的输出形态边界：相邻阶段做的事不能重叠（如「收集素材」阶段不要输出"提纲"，「列提纲」阶段不要重复列素材点）。User Flow 写出每步喵老师/AI/UI 应该呈现给用户的"形态"（一句话总结 / 三段结构化提纲 / 列表 / 卡片 等）。 内部协议字段不能泄漏到用户层：LLM 输出含 json 块、[[SIGNAL]] 标记、markdown 加粗等"给后端解析"的内容时，前端展示前必须 strip。如有 LLM JSON 协议，spec 必须显式列出"内部信号 vs 用户可见内容"边界。 主流程默认 ≠ 全部需求，没回答 = 默认"不支持" 并写进 Boundaries。
   • Commands：需要跑的命令（测试/构建/lint）
   • Structure：涉及的文件/模块列表。spec §4 里出现 image_url / file_path / binary blob 这类字段时，必须配套问"binary 文件怎么存？路径模式？静态服务挂哪？"——schema-as-truth 是常见误区，字段存在不等于实现就绪。
   • Style：编码规范（如有特殊要求）
   • Testing：测试策略（单元/集成/E2E）
   • Boundaries：非目标（绝不做什么）
   • Data Migration：涉及持久化（DB / 文件 / 缓存）变更时必填，否则写 N/A。问：现有 N 行数据怎么办？是否需要回填脚本 / 启动迁移 / 新代码兼容老数据？典型盲区："加字段 + 按字段过滤但不回填 → 老数据全部消失"
3. 问 complexity: simple | complex：
   • 1-2 文件 / 单模块 → simple
   • 跨模块 / 改架构 / 改 DB → complex
4. 每段填完立即写入文件（增量更新）。
5. 运行 harness plan validate <path>，不过就修。
6. 告诉用户：/harness-execute <path>。

硬约束

• 起草模式必须把讨论过的具体细节（文件名、约束、边界）写进 spec，不允许笼统归纳丢信息
• Boundaries 必须列具体项，不允许空/模糊
• validate 不通过不能结束
• 用户没明确同意的段落不写入文件
• spec 没过 validate 不能开工
• 不允许偷懒用"通用目标"代替"可验证的成功标准"