spec-define

name	spec:define
description	Use when creating a feature specification from requirements - triggers on /spec:define, 写 spec, 定义规范, 功能说明, or when needing deep code research before defining what to build

Spec 定义工作流 (Define)

将需求/想法转化为一份严谨的功能规范文档 spec.md，包含根因分析、视觉需求、功能需求、文件清单和边界情况。

产物: specs/[feature_name]/spec.md

⚠️ 交付标准（写之前必读）

你生成的 spec.md 必须同时满足以下 6 项硬指标，任何一项不通过禁止提交：

#	自检项	合格标准
1	file:/// 可点击源码链接	≥ 3 处。格式：[文件名:L行号](file:///绝对路径#L行号)。从 grep/读取返回值复制绝对路径，反斜杠换正斜杠。纯文字行号不合格
2	ASCII 布局图	视觉需求章节必须含 ≥ 1 张 ASCII 字符布局图，画出改动前后的元素排列对比。禁止仅用文字描述
3	代码片段	≥ 2 处 fenced code block（根因原始代码 + 修复方案代码）
4	边界情况	≥ 4 条，每条含：场景 + 风险 + 缓解策略
5	现有机制复用说明	明确列出复用了哪些已有变量/函数/CSS 类，以及为什么不需新增逻辑（如适用）
6	文件清单表格	Markdown 表格，列出所有改动文件

执行指令

1. 上下文加载

• 阅读 memory/constitution.md 确认技术栈与编码规范约束
• 仔细查看用户附带的所有图片（截图/设计稿）
• 如有用户指定的 feature_name，以此为产物目录名；否则从需求描述中提取关键词作为目录名

2. 深度代码调研（禁止跳过）

定量红线：调研阶段必须执行 grep_search 或文件读取 至少 5 次才允许进入撰写阶段。不足 5 次说明调研深度不够。

必须完成：

• 定位受影响代码：搜索至少 2 个关键词（类名、CSS 选择器、函数名），读取每个命中文件的完整上下文（前后至少 30 行）
• 追溯现有机制：找到相关的 state 变量、computed 属性、composable 函数，理解它们的读写链路。必须回答："现有的哪些机制可以复用？哪些不能？"
• 历史修复记录：搜索 UPDATE_LOG.md 和 README.md，确认是否有过类似改动或回归风险
• 记录绝对路径：将每个相关文件的绝对路径（从工具返回值中获取）记录下来，后续用于构建 file:/// 链接
• 严禁仅凭用户描述就开始撰写规范，必须用代码事实支撑每一个结论

3. 起草规范

• 仅创建/更新一个文件: specs/[feature_name]/spec.md
• 禁止创建 checklist 清单文件或单独的分析文件
• 语言要求: 所有输出及文档内容必须使用简体中文

4. 文档结构

4.1 背景

• 简述问题/需求的来龙去脉
• 每个技术结论必须附带可点击的 file:/// 源码链接
• 如有相关历史改动，引用 UPDATE_LOG.md 中的版本号和条目标题

4.2 视觉需求

• 必须包含 ASCII 布局图，用代码围栏包裹，画出改动前后的元素排列对比
• 禁止仅用文字描述视觉效果

4.3 功能需求

• 根因分析：逐条列出每个技术原因，每条附 file:/// 源码链接
• 具体修复方案：按改动点逐个列出，每个点必须包含目标文件与行号（file:/// 链接）和改动前后代码片段
• 现有机制复用清单：明确列出"复用了哪些已有变量/函数"及理由

4.4 涉及文件清单

• Markdown 表格列出所有需改动文件、改动类型（新增/修改/删除）和说明

4.5 边界情况

• 至少 4 条边界场景
• 每条必须包含：场景描述 + 风险分析 + 缓解策略
• 典型必查：临界值抖动、溢出/越界、与其他机制的冲突、高度变化对下游布局的影响

5. 出厂自检（强制执行）

创建 spec.md 后，必须立即用 grep 搜索自己写的 spec.md 中的 file:///：

• 如果搜索结果数 < 3，立即编辑 spec.md 补充链接直到 ≥ 3，然后再次搜索验证
• 同时检查边界情况条目数是否 ≥ 4，不足则补充

6. 输出结果

向用户展示所创建的 spec.md 摘要，并在回复末尾附带以下自检表：

| 自检项 | 要求 | 实际 | 达标 |
|--------|------|------|------|
| file:/// 链接数 | ≥ 3 | ? | ✅/❌ |
| ASCII 布局图 | 有 | 有/无 | ✅/❌ |
| 代码片段数 | ≥ 2 | ? | ✅/❌ |
| 边界情况条目 | ≥ 4 | ? | ✅/❌ |
| 机制复用说明 | 有 | 有/无 | ✅/❌ |
| 文件清单表格 | 有 | 有/无 | ✅/❌ |

完成后提示用户：下一步运行 /spec:architect 生成实施计划。