spec-propose

name	spec-propose
description	在需求提案阶段以“人主导、AI 辅助”的方式梳理代码现状、逐轮澄清需求，并在 `docs/changes/templates/` 下为单个需求创建 `spec.md`、`tasks.md`、`log.md`。当用户要求先做方案设计、先写规格文档、先澄清再实现、进入 propose/spec 阶段，或明确要求在编码前完成设计审视与确认门控时使用。

spec-propose

协同技能

在执行本 skill 时，同时遵守 ../../references/full-sdd-lifecycle.md 中 spec-propose 阶段的协同规则。

• 当需求本身仍然模糊时，先借用本插件 skills/idea-refine/SKILL.md 做问题收敛
• 生成 spec.md 时，继承本插件 skills/spec-driven-development/SKILL.md 的六大核心域
• 生成 tasks.md 时，继承本插件 skills/planning-and-task-breakdown/SKILL.md 的依赖拆解与验收口径
• 本 skill 是阶段编排器；同目录基础 skill 负责方法论，本 skill 负责门控、文档落盘和等待确认

目标

在编码前完成提案阶段文档，而不是直接进入实现。

• 基于现有代码锁定事实，并为每个关键结论提供代码出处
• 通过逐轮提问澄清范围、约束、边界条件和取舍
• 在 docs/changes/templates/<需求目录>/ 下生成 spec.md、tasks.md、log.md
• 在所有待澄清项处理完且用户显式确认前，禁止进入 Apply 或任何编码动作

执行顺序

按下面顺序执行，不要跳步。

1. 分析代码现状

先阅读仓库内与需求相关的代码、配置、文档和测试，再开始提问。

• 将每个结论写成“事实”，不要写成未经验证的猜测
• 为每个关键结论记录代码出处，优先使用文件路径和具体位置
• 将现状归纳为最小必要集合：已有能力、缺口、约束、风险点、影响面
• 若需求与当前代码明显冲突，先记录冲突，再围绕冲突提问

2. 逐轮澄清需求

一次只问一个问题，或一组紧密相关的问题。

• 优先提问会影响架构、接口、数据模型、兼容性、交付边界的问题
• 每轮尽量给出 2-3 个选项，并标注推荐项
• 为每个选项补一句影响说明，帮助用户快速决策
• 主动做 YAGNI 裁剪：把 nice to have 和可以延后的建议明确标注为“后续再议”
• 未澄清完前，不要产出假定已经确认的实现细节
• 如果问题之间存在依赖，先问上游问题，再问下游问题

推荐问题格式：

问题：是否需要兼容旧接口返回结构？

- 选项 A（推荐）：完全兼容旧结构
  影响：前端和调用方无需改动，但实现复杂度更高
- 选项 B：新增版本化接口
  影响：边界更清晰，但需要调用方配合切换
- 选项 C：允许直接替换
  影响：实现最简单，但存在明显升级风险

3. 创建需求目录

在 docs/changes/templates/ 下为当前需求创建一个新目录。

• 每个需求只对应一个目录
• 目录名使用简洁、稳定、可读的 kebab-case
• 不覆盖已有目录；若同名目录已存在，先检查是否为本次需求复用对象，否则换一个更具体的目录名
• 目录内必须生成 spec.md、tasks.md、log.md

4. 生成 spec.md

生成 spec.md 时必须使用 $spec-create 的结构化写法；如果无法直接调用，也要保持同等结构化程度。

并且必须补齐本插件 skills/spec-driven-development/SKILL.md 中强调的关键域：

• 目标与成功标准
• 执行命令
• 项目结构与边界
• 代码风格与示例
• 测试策略
• Always / Ask First / Never 边界

至少覆盖以下内容：

• 代码现状：当前实现、关键入口、相关依赖、已有限制，每个结论附代码出处
• 功能点：本次需求要解决的用户价值、行为变化和边界
• 变更范围：会修改的模块、不会修改的模块、外部影响面
• 风险：兼容性、数据、安全、性能、迁移、回滚等风险
• 技术决策：当前已确认的方案选择、放弃方案及原因
• 待澄清：仍需用户确认的问题，必须显式列出，不得隐藏在正文叙述中

若存在未解决问题，spec.md 必须反映这些问题仍处于待确认状态，而不是假装已定稿。

5. 生成 tasks.md

将任务拆成可执行、可验收的条目，但保持“提案阶段”语义。

• 使用 Markdown 清单或表格表达任务状态
• 将任务分成至少三类：事实分析、需求澄清、后续实现任务
• 将所有实现类任务标记为 blocked / pending，直到用户显式确认
• 不把“开始编码”写成已执行动作
• 对高风险任务补充依赖和前置条件
• 任务粒度尽量遵循本插件 skills/planning-and-task-breakdown/SKILL.md 的 S/M 任务标准，避免直接生成 XL 级任务

推荐结构：

# tasks

## 已完成
- [x] 分析相关代码现状并记录出处
- [x] 完成关键问题澄清

## 待确认
- [ ] 用户确认提案文档可进入 Apply
- [ ] 用户确认仍未关闭的取舍项

## 实施任务（确认后执行）
- [ ] 更新后端接口
- [ ] 补充测试
- [ ] 准备回滚和验收说明

6. 生成 log.md

创建即可，内容可暂时为空，后续记录apply阶段的决策变更、用户反馈、实施过程中的发现等。

硬门控

始终执行下面约束：

• 只要仍有待澄清项，就不要进入 Apply
• 即使需求看起来很简单，也不要跳过提案阶段的设计审视
• spec.md、tasks.md、log.md 生成完成后，必须等待用户显式确认
• 确认前禁止修改业务代码、测试、配置、数据库迁移或接口实现
• 若用户直接要求“顺手改掉”，先提醒当前仍处于 propose 阶段，再等待确认
• 若发现需求已足够清晰，也不能跳过文档落盘；至少要生成最小闭环提案文档

质量检查

交付前自行检查：

• docs/changes/templates/<需求目录>/ 是否存在且只包含当前需求的三个文件
• spec.md 是否包含代码现状、功能点、变更范围、风险、技术决策、待澄清
• tasks.md 是否把实现任务保持为未开始状态
• log.md 是否已创建
• 是否存在没有代码出处的关键结论
• 是否在用户确认前避免了任何编码动作

输出要求

向用户汇报时至少包含：

• 新建的需求目录路径
• spec.md、tasks.md、log.md 已生成
• 当前仍未关闭的待澄清项
• 是否满足进入 Apply 的条件
• 若尚未确认，明确提示“等待用户显式确认后再进入实现阶段”

最后阶段

• 完成所有任务后再docs/changes/templates/下修改README.md，添加新需求目录的链接和简要说明。
• 不允许在main\master分支进行开发，必须创建一个新的 feature 分支进行开发，命名格式为 feature/<需求目录>。