| name | hf-traceability-review |
| description | 适用于 code review 通过后判断追溯完整性、用户显式要求追溯评审的场景。不适用于评审代码质量（→ hf-code-review）、评审测试质量（→ hf-test-review）、阶段不清（→ hf-workflow-router）。 |
HF Traceability Review
评审证据链追溯完整性：spec→design→tasks→impl→test/verification→status。防止"代码能跑但不再匹配已批准工件"。UI surface 还要追溯 ui-design.md 的 visual invariants / token / contract 到实现与截图证据，防止只证明"元素存在"。运行在 hf-code-review 之后，决定是否可进入 hf-regression-gate。
Methodology
本 skill 融合以下已验证方法。每个方法在 Workflow 中有对应的落地步骤。
| 方法 | 核心原则 | 来源 | 落地步骤 |
|---|
| End-to-End Traceability | 检查从需求到实现的完整追溯链，确保每条需求可通过设计、任务、实现、验证四层逐级追溯 | IEEE 830-1993 / ISO 26550 需求追溯实践 | 步骤 2 — 多维评分；步骤 3 — checklist 审查 |
| Zigzag Validation | 每条 FR 前向追溯到设计决策，设计决策后向追溯到需求——双向验证防止断链 | 项目化实践（需求追溯通用方法） | 步骤 3.1/3.2 — 规格-设计/设计-任务双向验证 |
| Impact Analysis | 发现不一致时判断影响范围是局部还是需要回流到上游节点 | 项目化实践（变更影响分析通用方法） | 步骤 4 — verdict；步骤 5 — review 记录 |
When to Use
适用：
- code review 通过后判断追溯完整性
- 用户显式要求追溯评审
不适用 → 改用：
- 评审代码质量 →
hf-code-review
- 评审测试质量 →
hf-test-review
- 阶段不清 →
hf-workflow-router
Direct invoke 信号："追溯评审"、"traceability review"、"帮我检查证据链完整性"。
Hard Gates
- traceability review 通过前不得进入 regression gate
- 输入工件不足不得开始评审
- reviewer 不修代码、不继续实现
Workflow
1. 建立证据基线
读已批准规格、设计、任务计划（默认 features/<active>/spec.md / design.md / tasks.md）、实现交接块、test-review/code-review 记录（默认 features/<active>/reviews/）、项目级约定、feature progress.md（默认 features/<active>/progress.md）。
1.5 Precheck：能否合法进入 review
检查：是否存在稳定可定位的上游工件、实现交接块与上游 review 记录是否一致、route/stage/profile 是否稳定。
- route/stage/证据冲突 → 写最小 blocked precheck record，
reroute_via_router=true
- route 明确但缺关键上游工件或稳定实现交接块 → 写最小 blocked record，下一步
hf-test-driven-dev
- precheck 通过 → 继续正式审查
2. 多维评分与挑战式审查
7 维度 0-10 评分：规格-设计追溯、设计-任务追溯、任务-实现追溯、实现-验证追溯、漂移与回写义务、整体证据链闭合度、UI 设计一致性追溯。任一关键维度 < 6 不得通过。
按 references/review-checklist.md 做正式审查。
每条 finding 必须带：
severity（critical / important / minor）classification（USER-INPUT / LLM-FIXABLE）rule_id（如 TZ2、TZ5、ZA3）
默认分类：
USER-INPUT：规格 / 设计本身发生冲突、范围变化需走 increment、行为是否正式纳入批准工件仍需真人拍板LLM-FIXABLE：trace anchor 缺口、任务/文档未回写、实现交接块与验证记录表述不清、局部证据链可定向补齐
3. 正式 checklist 审查
3.1 规格-设计链：设计决策是否可追溯到规格需求？
3.2 设计-任务链：任务是否覆盖设计中的关键决策？
3.3 任务-实现链：实现是否完成任务的完成条件？触碰工件是否一致？
3.4 实现-验证链：验证证据是否锚定到当前实现？RED/GREEN 是否可追溯？
3.5 整体闭合：有没有断链？approved 工件与当前代码是否仍然一致？
3.6 UI 设计一致性追溯：若触碰 UI surface，是否从 ui-design.md 的 UI Implementation Contract 追到 tasks、实现文件、测试/浏览器截图证据？是否只证明元素存在而没有证明符合 visual invariants / token / forbidden drift？
4. 形成 verdict
通过：证据链完整，可进入 regression gate需修改：findings 可定向补齐追溯 → hf-test-driven-dev阻塞：核心链路断裂/工件与代码严重不一致 → hf-workflow-router
4A. Verdict 写回闸门
在返回结论前，必须先把 verdict 收敛成唯一下一步 + 最小结构化字段。不要只写自然语言结论。
| 场景 | conclusion | next_action_or_recommended_skill | reroute_via_router | 最少必须写出的字段 |
|---|
| precheck blocked：route / stage / 证据冲突 | 阻塞 | hf-workflow-router | true | record_path、workflow blocker、关键冲突说明 |
| precheck blocked：缺关键上游工件或稳定实现交接块 | 阻塞 | hf-test-driven-dev | false | record_path、缺失工件、为什么当前无法继续 traceability review |
正式审查后 需修改 | 需修改 | hf-test-driven-dev | false | record_path、key_findings、finding_breakdown、需要补齐的 trace anchor / 回写项 |
正式审查后 通过 | 通过 | hf-regression-gate | false | record_path、链接矩阵、剩余非阻塞提示（若有） |
正式审查后 阻塞 | 阻塞 | hf-workflow-router | true | record_path、核心断链点、为什么不能定向回修 |
约束：
needs_human_confirmation 固定为 false- 除
通过 且确无问题外，key_findings 不得留空
- 只允许一个 canonical
next_action_or_recommended_skill
- 若输出不能映射到上表中的一行，说明 verdict 还没收敛好，不能返回
5. 写 review 记录
保存到 项目声明的 review record 路径；若无项目覆写，默认使用 features/<active>/reviews/traceability-review.md（全 feature 一次性 review，scope 省略；若同一 feature 内多次复审，追加日期或序号后缀）。参考 references/traceability-review-record-template.md。
Output Contract
完成时产出：
- Review 记录（保存到 项目声明的 review record 路径；若无项目覆写，默认使用
features/<active>/reviews/traceability-review.md）
- 链接矩阵（spec→design→tasks→impl→test 映射）
- 明确 verdict 和唯一下一步
- workflow blocker 时显式写明
reroute_via_router=true
Reference Guide
| 文件 | 用途 |
|---|
references/review-checklist.md | traceability review checklist 与 rule IDs |
references/traceability-review-record-template.md | 追溯评审记录模板与结构化返回契约 |
Red Flags
- 不读上游工件就做追溯判断
- "代码能跑"等同于"追溯完整"
- 忽略规格/设计与代码的不一致
- 返回多个候选下一步
Common Rationalizations
| 借口 | 反驳 / Hard rule |
|---|
| "spec → code 链路抽样几条就行。" | Hard Gates: 必须全量映射 spec 段 → design 元素 → task → impl → 测试；抽样 → finding。 |
| "缺一两条 backward link 不影响交付。" | Workflow stop rule: backward traceability 缺失会让 hf-completion-gate 无法判定 DoD 全覆盖。 |
| "我自己补缺失的 traceability 条目。" | Hard Gates (soul.md): 评审者只产出 finding，traceability 条目由作者补。 |
Verification
