requirements-traceability

用途

这是一个面向可追溯性工程的技能，用于创建或审计从需求到设计、再到代码、测试和验证证据的完整链条。目标是产出一份小而高信号的追溯矩阵，清晰展示哪些需求在范围内、在哪里实现、如何被验证。

输入（缺失时需询问）

需求来源按优先级依次为：规格文档、ADR、工单、PR 描述；docs/requirements*.md（若存在）。此外还需要设计制品（ADR、架构文档、图表，若存在），实现范围（改动文件、模块或提交范围），以及测试套件入口和运行方式。

需求 ID 约定

优先使用稳定 ID，例如 REQ-001 / NFR-001。若不存在 ID，则提出一个最小约定并在矩阵中一致使用；未经批准不得重命名现有 ID。

工作流程

枚举需求（不猜测）：尽可能逐字提取显式需求；隐式需求列为 INFERRED-… 并请求确认；范围保持精简，仅包含受改动/PR 影响的需求。
需求 → 设计：为每条需求链接最近的设计制品，如 ADR（docs/adr/ADR-…）、模块设计文档、API 规范/schema。若没有设计制品，记录 Design: MISSING，并建议补充最小的有用制品（通常是一份简短 ADR 或 README 章节）。
需求 → 实现：链接文件与关键类型/函数、配置/功能开关、迁移或基础设施变更（如相关）。
需求 → 验证证据：每条范围内需求至少有一条验证路径，包括单元/集成测试、验收测试、UI 需求的视觉回归测试、安全需求的安全证据、延迟/吞吐/内存预算的性能证据，以及作为最后手段的人工验证步骤（需包含负责人和日期）。证据必须具体（路径、命令、日志），“看起来不错”不算证据。
产出：追溯矩阵、缺口清单（阻断项与后续项）、以及按最小改动优先的补全建议。

追溯矩阵模板

Req ID	Requirement	Maturity	Design Ref	Impl Ref	Tests	Evidence	Status
REQ-001	…	Draft	ADR-001	`src/...`	`tests/...`	`docs/quality/...`	✅/⚠️/❌

成熟度状态

技能跟踪制品在开发生命周期中的成熟度：Draft（初步捕获、未验证，需求已识别）、Review（利益相关者评审中，已记录在 PR/规格中）、Approved（接受实现，利益相关者签字）、Implemented（代码完成，已合并到主分支）、Verified（已测试，测试通过）、Validated（利益相关者接受，UAT 签字）。成熟度列有助于识别哪些需求已准备好进入各个开发阶段。

缺口严重度规则

❌ 阻断项：范围内需求没有实现链接，或没有验证路径。

⚠️ 后续项：实现存在但证据不完整（例如关键回归仅有手工步骤）。

ℹ️ 备注：不影响可追溯性的文档/格式改进。

输出格式

Traceability Report: {change}

Requirements Enumerated

REQ-…

Traceability Matrix

{table}

Gaps

❌ {Req} missing {design/tests/evidence}
⚠️ {Req} has {partial evidence}

ZDP 集成（可选）

在 ZDP（Zestic AI Development Process）生命周期中使用时，技能提供额外指引，独立使用时该节可忽略。ZDP 定义完整制品链：PVVH -> Business Scenarios -> Domain Model -> Design Brief -> Architecture Doc -> Prompt/Agent Specs -> Implementation -> Test Cases -> UAT -> Monitoring。在 ZDP 上下文中追溯需求时，需扩展矩阵以覆盖该链条，并在标准 REQ ID 旁加入 ZDP 制品 ID：

Req ID	ZDP Artefact	Requirement	Design Ref	Impl Ref	Tests	Evidence	Status
REQ-001	BS-003	...	ADR-001	src/...	tests/...	...	...

交叉引用

如可用，可与以下项协同：/business-scenario-design（业务场景 ID 用于可追溯性）、/product-vision（PVVH 作为追溯链根节点）、/responsible-ai（负责任 AI 需求的追溯）。

约束

不得声称无法指向（路径/测试/命令/日志）的覆盖；对于回归问题，优先新增/扩展测试而非新增人工步骤；矩阵保持小巧且范围明确，细节通过链接引出。