统一验证

四合一验证 Skill：文档对齐 + 实现正确性 + UI 设计对齐 + 开发就绪检查，替代原 devdocs-review、devdocs-requirements-alignment、devdocs-ui-alignment。

语言规则

支持中英文提问
统一中文回复
使用中文生成报告

定位

devdocs-verify --docs  ：各层文档之间是否对齐（原 requirements-alignment）
devdocs-verify --impl  ：实现是否正确（原 review）
devdocs-verify --ui    ：UI 设计和实现是否对齐（原 ui-alignment）
对抗式验证            ：代码质量是否合格（dev-workflow 内置）
devdocs-verify --readiness ：开发就绪条件是否满足（pipeline 关卡）

互补关系：--docs 检查"文档写对了没"，--impl 检查"代码做对了没"，--ui 检查"界面做对了没"，--readiness 检查"能开工了没"，对抗式验证检查"代码写得好不好"。

触发条件

需求/设计/测试文档完成后（--docs）
任务开发完成后、对抗式验证之前（--impl）
UI 相关任务开发完成后（--ui）
任务拆分完成、进入开发前（--readiness）
用户要求检查文档/实现/UI 对齐

运行模式

/devdocs-verify                    → 自动检测维度（见下方规则）
/devdocs-verify --docs             → 仅文档对齐（三层检查）
/devdocs-verify --docs --layer1    → 仅原始需求 → 需求文档
/devdocs-verify --docs --layer2    → 仅需求文档 → 系统设计
/devdocs-verify --docs --layer3    → 仅需求文档 → 测试用例
/devdocs-verify --impl             → 仅实现正确性（AC + 设计 + 追溯）
/devdocs-verify --impl --ac        → 仅 AC 满足度
/devdocs-verify --impl --design    → 仅设计符合度
/devdocs-verify --impl --trace     → 仅追溯完整性
/devdocs-verify --ui               → 仅 UI 设计对齐（两阶段）
/devdocs-verify --ui --design      → 仅设计稿 ↔ 需求
/devdocs-verify --ui --impl        → 仅设计稿 ↔ 实现
/devdocs-verify --readiness          → 开发就绪检查（进入 dev-workflow 前的质量关卡）
/devdocs-verify T-01 T-02          → 指定任务范围（自动 --impl）

自动检测规则

无参数调用时，根据项目状态自动选择维度：

检查是否存在最新 05-test-report.md → 有则 --impl 辅助判断
检查当前开发阶段：
- 有 03-test-cases.md 但无代码提交 → --docs（文档阶段）
- 有代码提交且任务进行中 → --impl（开发阶段）
- UI 任务 + 有设计稿 → --impl + --ui
无法判断 → 询问用户

工作流程

1. 确定验证维度（自动检测或用户指定）
   │
   ▼
2. 读取 DevDocs 文档
   ├── 01-requirements.md（AC 列表、原始需求）
   ├── 02-system-design.md（设计规范）
   ├── 03-test-cases.md（测试用例、追溯矩阵）
   └── 05-test-report.md（如存在，辅助 --impl 判断）
   │
   ▼
3. 按维度执行检查
   ├── --docs：三层对齐检查
   ├── --impl：三维度正确性审查
   ├── --ui：两阶段设计对齐
   └── --readiness：四维度就绪检查
   │
   ▼
4. 生成验证报告
   │
   ▼
5. 修复建议与路由

维度 A：文档对齐（--docs）

验证各层文档之间是否对齐，防止需求精化过程中的偏移和遗漏。

原始需求（用户原话）
    │
    ├─ 层 1：原始需求 → 需求文档（F/US/AC）
    ├─ 层 2：需求文档 → 系统设计
    └─ 层 3：需求文档 → 测试用例

每层独立可执行，越早发现偏移，修复成本越低。

层 1：原始需求 → 需求文档

前提：需求文档中应包含 ## 0. 原始需求 章节。

文档类型	`## 0. 原始需求` 状态	层 1 行为
新建文档	必须存在	正常执行语义对齐检查
历史/Retrofit 文档	可能不存在	输出 `⏭️ 前置缺失`，跳过层 1

检测类型：遗漏（原始需求未被 F/US/AC 体现）、过度扩展（超出原始需求范围）、偏移（语义偏离）。

层 2：需求文档 → 系统设计

检查 F → 设计模块映射、AC → 实现路径、设计孤立项。

层 3：需求文档 → 测试用例

检查 AC → 测试用例映射、正向路径覆盖、异常路径覆盖。复用 devdocs-sync --audit 的孤立编号检测能力。

维度 B：实现正确性（--impl）

验证代码实现是否正确——AC 满足度、设计符合度、追溯完整性。

B1：AC 满足度审查

逐条验证实现是否匹配验收标准。

读取 01-requirements.md 中所有 AC
通过 @satisfies 标注 + 代码搜索定位实现
语义判断实现是否匹配 AC 描述（不仅检查标注存在性）
对每条 AC 给出判定：✅ 满足 / ⚠️ 部分满足 / ❌ 未满足

辅助判断：如存在最新 05-test-report.md，用实际测试通过率辅助判断 AC 满足度——测试全部通过的 AC 可提高判定信心，测试失败的 AC 需重点审查。

B2：设计符合度审查

检查项	说明	严重程度
接口签名一致性	实际参数/返回值与设计文档不符	Blocker
模块职责偏离	模块承担了设计中未分配的职责	Blocker
数据流符合度	数据流转路径与设计不符	Warning
组件边界	组件间依赖关系与设计不符	Warning

B3：追溯完整性审查

检查 @satisfies/@verifies 覆盖率。复用 devdocs-sync --trace 的扫描能力。

维度 C：UI 设计对齐（--ui）

验证 UI 设计和实现是否对齐——两阶段验证。

C1：设计稿 ↔ 需求对齐

支持三种设计稿来源：Pencil .pen 文件、截图/图片、Figma（通过截图或 MCP）。

检查设计稿是否覆盖 01-requirements.md 中 UI 相关 AC。

C2：设计稿 ↔ 实现对齐

获取实现截图，与设计稿逐维度对比。默认路径：要求用户提供实现截图；自动化路径：如环境中有浏览器 MCP 工具可用，自动截图。

截图获取方式

优先级	方式	条件
1（默认）	用户提供实现截图	始终可用
2（自动）	浏览器 MCP 自动截图	环境中有 Playwright/Chrome DevTools MCP

对比维度

维度	检查内容	严重程度
布局结构	元素排列、层级关系	P1
间距	元素间距、内外边距	P2~P3
颜色	主色、辅色、文字色	P2~P3
字体	字族、字号、字重	P2~P3
交互状态	hover/active/disabled/error	P1
响应式	不同断点下的布局变化	P2~P3

UI 降级策略

条件	行为
无设计稿输入	不可运行——提示用户提供设计稿
有设计稿，无浏览器 MCP	阶段 1 正常；阶段 2 要求用户提供实现截图
有浏览器 MCP，无设计稿 MCP	要求用户提供设计稿截图

工具说明：Pencil MCP（mcp__pencil__*）、Playwright MCP（mcp__playwright__*）、Chrome DevTools MCP（mcp__chrome-devtools__*）为可选依赖，按可用性自动选择。无 MCP 时降级为用户提供截图，不影响验证能力。

维度 D：开发就绪检查（--readiness）

验证任务文档是否达到开发就绪状态——在 dev-tasks → dev-workflow 过渡时作为质量关卡。

与 --docs 的区别：--docs 检查文档层间对齐（漂移检测），--readiness 检查任务级开发就绪条件（具体性、一致性、可执行性）。

D1：AC ↔ 测试用例对齐

检查每条 AC 是否有对应的测试用例设计：

读取 01-requirements.md 中所有 AC
读取 03-test-cases*.md 中的追溯矩阵
逐条检查 AC → UT/IT/E2E 映射
输出未覆盖的 AC 列表

D2：任务文件路径具体性

检查 04-dev-tasks*.md 中每个任务的文件路径是否具体可执行：

检查项	合格标准	不合格示例
文件路径	明确到文件名	"修改相关文件"
方法/接口	明确到方法名或接口名	"调整接口"
测试方法	指定测试类型和编号	"编写测试"

D3：任务依赖无环

检查任务依赖关系是否存在循环：

从 04-dev-tasks*.md 提取所有任务依赖关系
构建有向图，执行拓扑排序
若存在环路 → 报告环路路径

D4：设计 ↔ 任务一致性

检查任务定义是否与系统设计一致：

任务引用的模块/接口在 02-system-design*.md 中存在
任务的文件路径与设计文档的代码结构一致
无孤立任务（任务未关联任何 F-XXX/AC-XXX）

CE 三个审查问题（--impl 专属）

--impl 审查完成后，必须追加回答：

"实现中最难的决策是什么？" — 识别技术复杂度核心
"拒绝了哪些替代方案？为什么？" — 确认决策有对比论证
"最不确信的部分是什么？" — 暴露隐性风险

问题分级

所有维度发现统一按优先级分级：

优先级	含义	处理方式
P1	阻塞发布	必须修复，建议转入 devdocs-dev-tasks
P2	应修复	建议修复，建议转入 devdocs-insights
P3	可优化	可选修复，记录备忘

P1 判定标准

--docs：原始需求遗漏（层 1）、AC 无设计支撑（层 2）、AC 无对应测试（层 3）
--impl：AC 未满足（❌）、接口签名与设计不符、模块职责严重偏离、核心 AC 无 @satisfies 标注
--ui：布局结构与设计稿不符、关键交互状态未实现、AC 描述的 UI 行为在设计稿中缺失
--readiness：AC 无对应测试用例（D1）、任务存在循环依赖（D3）、孤立任务无需求关联（D4）

P2 判定标准

--docs：原始需求偏移（层 1）、AC 缺异常路径测试（层 3）
--impl：AC 部分满足（⚠️）、数据流轻微偏离、@satisfies 覆盖率 < 80%
--ui：间距/颜色/字体的显著偏差、响应式断点差异
--readiness：任务文件路径不够具体（D2）、设计↔任务文件路径不一致（D4）

P3 判定标准

--docs：过度扩展（层 1）、设计孤立项（层 2）
--impl：非核心代码缺少标注、非关键路径微偏离
--ui：间距/颜色/字体的轻微偏差
--readiness：任务描述过于简略但路径具体

输出文件

维度	输出文件
--docs / --impl / --ui	`docs/devdocs/verify-report.md`
--readiness	`docs/devdocs/readiness-report.md`

详细模板参见 templates/verify-report.md（--docs/--impl/--ui）和 templates/readiness-report.md（--readiness）

上下文管理

分批原则

--docs：按层级分批（层 1、层 2、层 3 各为一个批次）
--impl：按任务 (T-XX) 或功能点 (F-XXX) 分批，每批完成全部三个子维度
--ui：按页面/组件分批
--readiness：一次性全量检查（通常任务数量有限，不需分批）

质量锚点

--docs：使用完备性验证——每层检查后核对已报告数量 == 输入编号总数
--impl：首个功能点的审查结果作为质量锚点，后续深度不低于首批
--ui：首个页面的检查结果作为质量锚点
--readiness：使用完备性验证——所有任务和 AC 均已出现在检查结果中

一致性自检

每批完成后对比检查：

判定标准跨批次一致（同类问题同等判定）
统计口径一致
（--docs）所有输入编号均已出现在输出矩阵中
（--impl）AC 语义判断深度不低于首批

约束

检查约束

必须读取所有相关 DevDocs 文档后再检查
--docs 层 1 依赖"原始需求"章节——新文档必须存在，历史文档若不存在则输出"前置缺失"并跳过
--impl AC 满足度必须语义判断，不仅检查标注存在性
--impl 设计符合度必须对照设计文档原文，不凭记忆
--ui 阶段 1 必须读取需求文档中的 UI 相关 AC
--ui 阶段 2 必须获取实现截图进行视觉对比
--ui 无设计稿输入时不可运行，必须提示用户提供
必须生成验证报告

分级约束

所有发现必须按 P1/P2/P3 分级
P1 必须列出修复建议
不将 P2/P3 升级为 P1（除非用户要求严格模式）
--impl 必须回答 CE 三个审查问题

安全约束

不修改代码，只生成报告
不修改 DevDocs 文档
不修改设计稿

上下文管理约束

后批次审查深度不低于首批次
每批完成后执行一致性自检
--docs 每层检查后验证编号完备性

Skill 协作

场景	协作 Skill	说明
开发完成	`/devdocs-dev-workflow`	被调用：任务完成后触发 --impl
对抗式验证	`/devdocs-dev-workflow`	协作：作为验证流程的前置步骤
需求完成	`/devdocs-requirements`	被调用：需求扩写后触发 --docs --layer1
设计完成	`/devdocs-system-design`	被调用：设计完成后触发 --docs --layer2
测试设计完成	`/devdocs-test-cases`	被调用：测试设计后触发 --docs --layer3
UI 任务完成	`/devdocs-dev-workflow`	被调用：UI 任务完成后触发 --ui
追溯扫描	`/devdocs-sync`	复用：标注扫描能力（追溯同步）
追溯检查	`/devdocs-sync`	复用：孤立编号检测（审计同步）
AC 缺失	`/devdocs-requirements`	路由：发现 AC 不完整时
设计偏离	`/devdocs-system-design`	路由：发现设计文档需更新时
测试缺失	`/devdocs-test-cases`	路由：发现测试缺失时
代码质量	`/code-quality`	互补：code-quality 关注代码质量约束
UI 开发	`/ui-orchestrator`	互补：路由开发 vs 验证对齐
知识沉淀	`/devdocs-compound`	前置：读取验证报告提取改进模式
开发就绪	`/devdocs-pipeline`	被调用：dev-tasks 完成后、dev-workflow 前的质量关卡

子 Agent 摘要格式

当本 Skill 作为子 Agent（通过 Task tool）运行时，返回以下结构化摘要：

skill: devdocs-verify
dimensions: [docs, impl, ui, readiness]  # 实际执行的维度
summary:
  total_p1: 0
  total_p2: 0
  total_p3: 0
  status: pass | fail | partial
  docs:
    layer1: pass | fail | skipped
    layer2: pass | fail | skipped
    layer3: pass | fail | skipped
  impl:
    ac_satisfaction: "X/Y satisfied"
    design_conformance: pass | fail
    traceability: "X% coverage"
    test_report_used: true | false
  ui:
    stage1: pass | fail | skipped
    stage2: pass | fail | skipped
  readiness:
    ac_test_coverage: "X/Y covered"
    path_specificity: pass | fail
    dependency_cycle: false
    design_task_consistency: pass | fail
blockers:
  - "P1: AC-003 未满足（--impl）"
output_files:
  verify: docs/devdocs/verify-report.md      # --docs / --impl / --ui
  readiness: docs/devdocs/readiness-report.md # --readiness

下一步

维度	结果	建议下一步
--docs 层 1 有遗漏	P1	`/devdocs-requirements --incremental` 补充 F/US/AC
--docs 层 1 有偏移	P2	与用户确认需求理解是否正确
--docs 层 2 有缺失	P1	`/devdocs-system-design` 补充设计
--docs 层 3 有缺失	P1	`/devdocs-test-cases` 补充测试用例
--impl 有 Blocker	P1	修复后重新运行 `/devdocs-verify --impl`
--impl 仅 Warning	P2	进入对抗式验证
--impl 设计偏离	-	`/devdocs-system-design` 更新设计文档
--ui 阶段 1 有缺失	P1	补充设计稿，覆盖缺失的 AC
--ui 阶段 2 有 P1	P1	修复实现后重新验证
--readiness AC 无测试	P1	`/devdocs-test-cases` 补充测试用例
--readiness 循环依赖	P1	`/devdocs-dev-tasks` 重新拆分任务
--readiness 路径不具体	P2	`/devdocs-dev-tasks` 细化任务定义
--readiness 全部通过	-	进入 `/devdocs-dev-workflow` 开发执行
全部通过	-	进入对抗式验证