adk-requirements-triage

Goal

• 将模糊需求收敛为可实现、可验证、可拆分的执行包。

Prerequisites

• 确认需求来源、owner、时间窗口和关键依赖方。
• 获取最小上下文：入口代码、现有行为、已知限制。

需求分类规则

类别	判定标准	处理方式
新功能	无现有代码对应	完整走 Workflow 8 步
增强	现有代码可扩展	重点分析影响面和兼容性
缺陷修复	行为偏离预期	先复现再定位，跳过部分规划步骤
技术债务	无功能变更	评估 ROI，低收益则推迟
配置变更	仅涉及配置文件	补迁移和回退步骤

优先级判断矩阵

优先级	业务影响	技术风险	时间紧迫度	处理策略
P0-紧急	核心功能阻断	高	立即	停下手头工作，立即处理
P1-重要	核心功能降级	中	本周	排入当前迭代
P2-一般	体验优化	低	本月	排入下个迭代
P3-低优	锦上添花	低	不急	积压，有空再做

Workflow

1. 探索式开场：需求宽泛时先用 references/exploratory-requirements-brief.md 发散 2-4 个方向，再收敛边界。
2. 结构化快速扫描：定位模块入口、现有实现、相关测试与依赖约束。
3. 识别关键疑问：列出阻塞规划的问题，并按高/中/低优先级排序。
4. 领域建模预检：对非纯配置/文案任务，先列出关键术语、实体、状态、接口、数据流和边界样例；字段缺失时不得进入实现。
5. 上下文充分性检查：确认接口契约、风险点、验证方式均可陈述。
6. 需求分类：按分类规则判定需求类别，选择对应处理方式。
7. 优先级判定：按矩阵评估业务影响、技术风险、时间紧迫度。
8. 触发路由判断：输出 core/optional 技能建议、触发理由与排除理由。
9. 需求拆分策略：若需求过大，按模块、层次、阶段或风险拆成可独立验收的需求包。
10. 产出需求包：目标、非目标、影响面、done-when、required evidence、artifact paths、blocker policy、验收标准、回退条件。
11. 明确下一步：给出可执行任务切分与责任边界（owner/scope）。

Discovery Template

• 嵌入式需求探索优先使用 references/embedded-discovery-brief.md。
• 需求发散与拷问开场使用 references/exploratory-requirements-brief.md。
• 当任务涉及芯片/板级约束、启动链、BSP、OS/runtime、驱动、组件、协议栈、设备应用、上位机/产测/诊断工具、构建调试、验证、发布、量产或现场维护时，必须先补齐目标层级、运行环境、接口边界和验证约束。
• 通用产品探索只作为辅助，不应冲淡 adk 的嵌入式全栈开发定位。

Commands

# 扫描现有实现和依赖
rg -n "TODO|FIXME|HACK|deprecated" <target_path>
rg -n "test|spec|contract|schema" <target_path>

# 匹配相关 skill
bash scripts/devkit.sh match --skill <skill-name> --text "<需求片段>"

# 查看变更范围
git diff --name-only <base>...HEAD

# 检查依赖关系
rg -n "import|require|include|#include" <target_path> | head -20

Evidence Template

- Goal / Non-goal / Done-when / Required Evidence / Artifact Paths / Blocker Policy:
- 需求分类: 新功能 / 增强 / 缺陷 / 技术债务 / 配置变更
- 优先级: P0/P1/P2/P3 + 判定依据
- Impact Scope:
- Domain Model: 术语 / 实体 / 状态 / 接口 / 数据流 / 边界样例 / 反例
- Acceptance Criteria:
- 拆分策略: 模块/层次/阶段/风险
- Migration/Config Decision:
- Spec Chain Decision:
- Install Scope Decision:
- Skill Routing (core/optional + reason):
- Key Risks:
- Missing Context:
- Suggested Task Breakdown:

Failure Handling

• 上下文不足时输出 needs-fix 并列出待补信息，不进入实现。
• 若需求混入多个无关问题，先拆分再继续。
• 优先级无法判定时，标记为 P2 并注明待确认。
• 需求分类模糊时，选择风险更高的类别处理。

与 adk-structured-requirements-questioning 的区别

• adk-requirements-triage: 需求结构化拆解与验收标准固化
• adk-structured-requirements-questioning: 结构化需求提问对齐，通过有序问题消除模糊

Quality Gate

• 输出必须包含目标、非目标、影响面、验收标准四项。
• 输出必须包含 done-when、required evidence、artifact paths 和 blocker policy；缺任一项时结论固定为 needs-fix。
• 非纯配置/文案任务必须包含 Domain Model；缺关键术语、实体/状态、接口或边界样例时不得进入实现。
• 至少给出一个关键风险及对应验证方式。
• 若充分性检查未通过，结论必须为 needs-fix，并列出缺失信息。
• 需求必须有明确分类和优先级。
• 拆分后的需求包必须各自具备独立验收标准。

合理化借口拦截

借口	现实	正确做法
"需求已经很清楚了"	模糊需求是 bug 的温床，口头"清楚"不等于书面可验证	按 SKILL.md 流程结构化拆解为目标/非目标/验收标准
"这个需求太简单不需要拆"	简单需求同样可能隐含边界条件和影响面	至少完成充分性检查与影响面分析
"用户说了就这样做"	用户描述的是期望，不是规格	转化为可测试的工程条目并获得确认