grill

name	grill
description	复杂任务前置反复盘问用户需求直到无歧义，输出 docs/requirements/<feature>.md 作为后续 plan/实施的事实来源。**触发场景**：用户给一句话模糊需求（如「优化购物车」「改下登录」「看看那个东西」）/ 复杂任务（判据见 im-agent-workflow.md 的「任务复杂度分级」表）/ 未提供 PRD / Figma / 飞书需求的需求；5 轮硬上限不收敛就停下让用户线下整理。
argument-hint	["需求描述"]
allowed-tools	Read, Write, Bash(mkdir *)

grill

复杂任务前置：反复盘问用户需求，直到无歧义，输出 docs/requirements/<feature>.md 作为后续 plan/实施的事实来源。

何时使用

任务类型	是否需要 grill
简单需求（改注释 / 调样式 / 单文件 fix）	❌ 不需要，直接做
中等需求（2-3 文件改、加个 utils）	△ 可选，看需求是否明确
复杂需求（判据见 .claude/rules/im-agent-workflow.md 的「任务复杂度分级」表）	✅ 强烈建议先 grill
一句话模糊需求（"优化购物车" / "改下登录"）	✅ 必须 grill

如果用户已经提供详细文档（PRD / 飞书需求 / Figma 链接），先 Read 这些资料，再用 grill 补齐缺失维度。

参数

$ARGUMENTS — 用户的原始需求描述（一句话或一段话）

执行步骤

Step 0: 检查现有材料

询问用户是否有：

• 已有的需求文档 / PRD / 飞书链接
• Figma 设计稿
• 类似已实现功能的参考

如有 → Read 后跳到 Step 2 补缺失维度。 如无 → 直接进 Step 1。

Step 1: 解析需求关键词

从 $ARGUMENTS 提取：

• 动词：加 / 改 / 删 / 优化 / 修复
• 对象：哪个功能 / 哪个模块
• kebab-feature 名：用于文件命名（如 "pin-conversation" / "recall-confirm"）

如果完全无法提取（例如 "看看那个东西" 这种），直接返回："需求太模糊，能否换种说法？给我一个动词 + 对象。"

Step 2: 五维度盘问（最多 5 轮）

每轮聚焦一个维度提问，禁止漫无目的发散。每轮提问后展示当前理解，让用户确认/修正。

维度 1：目标对象（What）

具体改什么？

你说"<原始需求>"，我需要先确认改的范围：
- 是 <候选 A>，还是 <候选 B>，还是 <候选 C>？
- 涉及的文件大概在 <猜测路径>，对吗？

举例：

• "优化购物车" → "是商品列表布局、结算流程、空状态提示、还是优惠券展示？"
• "改撤回消息" → "是撤回的触发方式、撤回后的视觉、撤回时间限制、还是撤回后的重新编辑？"

维度 2：范围边界（Scope）

哪些不改？

这次改动：
- ✅ 我会处理：<列点>
- ❓ 这些是否包含：<候选边界>
- ❌ 我不会动：<显式排除>

确认一下范围对不对？

特别问：

• 端：桌面 / 移动 / 都改？
• 角色：买家 / 卖家 / 客服 / 都改？
• 路由：仅当前页 / 全站？

维度 3：触发条件（When/Where）

什么场景下生效？

这个改动什么场景下用户会看到？
- 登录态 / 游客？
- 特定路由 / 全站？
- 某个状态下（首次进入 / 数据为空 / 接口失败）？

维度 4：异常处理（Edge cases）

不正常情况怎么办？

异常情况：
- 接口失败：显示错误提示？回退到默认状态？还是静默？
- 数据为空：空状态文案？还是不渲染？
- 网络慢：loading 态怎么展示？
- 用户没权限：提示登录？还是隐藏入口？

维度 5：验收方式（Acceptance）

前端的核心——你怎么判断改对了？

我改完后，你怎么验证：
- 我应该让你点哪个按钮 / 进哪个页面？
- 你期望看到什么变化？
- 有什么之前没有的现象现在应该出现？
- 有什么之前的现象现在不应该出现？

这一步是产出 手测步骤 的核心，决定 docs/requirements/ 里"验收清单"章节的内容。

Step 3: 5 轮硬上限检查

如果到了第 5 轮还有维度没问清：

不要继续问。直接告诉用户：

我们已经讨论了 5 轮但 <维度 X> 还没明确。这通常说明需求本身需要先线下整理。建议：
1. 你先把 <维度 X> 的几种方案列出来
2. 或者先做一个最小可行版本，跑起来看效果再迭代
3. 或者跳过 grill 直接让我按当前理解做（风险：可能返工）

你想怎么办？

理由：5 轮还问不清说明需求本质模糊，AI 继续问只会消耗信任，不会产生新信息。

Step 4: 生成 requirements 文件

确认所有维度后，写入 docs/requirements/<kebab-feature>.md。如果目录不存在，先 mkdir -p docs/requirements。

文件模板：

# 需求：<一句话标题>

> 生成时间：<YYYY-MM-DD>
> 来源：用户原话 "<$ARGUMENTS>"

## 目标
<用户真正想要什么 — 1-2 段，禁止空话>

## 范围

### 包含
- <列点>
- <列点>

### 不包含
- <显式排除项>

## 触发条件
- 用户场景：<什么角色 / 什么状态 / 什么路由>

## 异常处理
- 接口失败：<期望行为>
- 数据为空：<期望行为>
- 其他边界：<期望行为>

## 验收清单（手测步骤）

按顺序操作，每步必须是可在浏览器中观察到的现象：

1. <步骤> → 期望看到 <现象>
2. <步骤> → 期望看到 <现象>
3. ...

## 已确认的边界条件
- <从 grill 中确认的关键约束 / 默认值 / 与现有功能的关系>

## 后续动作建议
- 涉及文件预估：<根据 .ai/INDEX.md 路由的相关文件，可空>
- 建议复杂度：简单 / 中等 / 复杂
- 建议下一步：/start-task <branch-name> 或直接开干

Step 5: 收尾

需求已澄清，写入：docs/requirements/<feature>.md

接下来：
- 复杂任务：建议 /start-task feat/<feature> 创建分支后开始
- 中等任务：可以直接开始改，参考 verifyClist 验收
- 不确定：把 requirements.md 给到 planner agent 让它出 plan

与其他命令/skill 的关系

关系	说明
上游：用户原始需求	grill 是把模糊需求转成结构化文档的入口
下游：planner agent	planner 必须先 Read requirements.md，plan 不能引入 requirements 外的假设
下游：test-assist skill	"验收清单"是 test-assist 写测试时的覆盖参考
下游：dev-debug skill	"手测步骤"是 dev-debug 启动浏览器后的检查清单
旁路：Figma / 飞书	grill 不替代视觉设计；有 Figma 链接先看图，再 grill 补维度

反模式（禁止）

• ❌ 5 个维度都问完之前就开始写代码
• ❌ 不展示当前理解就连续追问（用户没法纠偏）
• ❌ 简单需求也强制 grill（噪音、惹用户烦）
• ❌ requirements.md 写满实现细节（那是 plan 的事，不是 grill 的事）
• ❌ 用户说"不要 grill 直接干"还继续问（不尊重）
• ❌ 5 轮还没问清继续问第 6 轮（必须停下报告）