| name | analyze |
| description | 制品一致性分析技能. 对 spec.md、design.md 和 tasks.md 做跨制品一致性与质量分析; 发现问题后全部自动修复（不设轮数上限）, 执行全程不询问用户、不中断等待交互. 若仍有不可自动消除的残留问题, 须完整打印后继续并正常结束本技能, 不得因残留问题判定失败或阻断后续步骤. 当用户提到分析制品、检查一致性、质量审查、或在 tasks 完成后需要验证时使用. |
OmniSpec 跨制品一致性与质量分析
目标
在实施之前, 识别三个核心制品(spec.md、design.md、tasks.md)之间的不一致、重复、模糊和规范不足的项目. 此技能必须在 tasks.md 成功生成后运行.
用户输入
在继续之前, 你必须考虑用户的消息内容(如果不为空).
操作约束
统一行为: 允许直接编辑 FEATURE_DIR 下的 spec.md、design.md、tasks.md（及修复所必需的最小范围改动）. 完成步骤 1–6 的检测后 必须进入步骤 7 的修复—验证循环. 不设轮数上限: 持续自动修复并重新检测, 直至单轮已无可自动应用的修复（收敛）. 全程 禁止向用户发起「是否修复」「是否继续」「是否采纳建议」等确认类提问; 禁止以只读分析报告代替自动修复而提前结束.
残留问题不得阻断: 收敛后若仍存在严重/高/中/低各级残留问题, 必须在输出中完整打印（含严重性、位置、摘要）; 本技能仍视为 正常完成, 禁止将残留问题记为技能失败、禁止触发「技能失败判定」或停表阻断 workflow; 调用方（含 omnispec 各 workflow）必须继续执行后续步骤（如 implement）.
章程权威: 项目章程(.infra/memory/constitution.md)在此分析范围内是不可协商的. 章程冲突自动为严重问题, 须通过编辑制品消除——不得稀释、重新解释或默默忽略原则. 若原则本身需变更, 须在分析之外的单独章程更新中进行; 禁止为「省事」而弱化章程要求.
执行步骤
完成下列步骤 0–6 后 必须执行步骤 7, 不得在 analyze 执行期间停下来等待用户输入.
0. skill执行开始时间打点记录
开始执行步骤之前，需要进行一些打点记录工作，记录本skill的执行时间到 start_time字段：
- 判断当前操作系统，windows还是linux系统;
- 针对不同操作系统运行脚本获取配置
windows:
Get-Date -Format "yyyy-MM-dd HH:mm:ss"
linux: date +"%Y-%m-%d %H:%M:%S"
- 将获取的时间记录到
start_time
1. 初始化分析上下文
-
判断当前操作系统, windows 还是 linux 系统;
-
针对不同操作系统从仓库根目录运行脚本
windows: scripts/powershell/check-prerequisites.ps1 --json --require-tasks --include-tasks
linux: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
-
解析 JSON 以获取 FEATURE_DIR 和 AVAILABLE_DOCS. 推导绝对路径:
-
SPEC = FEATURE_DIR/spec.md
-
DESIGN = FEATURE_DIR/design.md
-
TASKS = FEATURE_DIR/tasks.md
如果任何必需文件缺失, 则以错误消息中止(指示用户运行缺失的先决条件命令).
对于参数中的单引号, 如 "I'm Groot", 使用转义语法: 例如 'I'''m Groot'(或尽可能使用双引号: "I'm Groot").
2. 加载制品(渐进式展示)
仅从每个制品加载最小必需的上下文:
从 spec.md:
- 概述/上下文
- 功能需求
- 非功能需求
- 用户故事
- 边缘情况(如果存在)
从 design.md:
从 tasks.md:
- 任务 ID
- 描述
- 阶段分组
- 并行标记 [P]
- 引用的文件路径
从章程:
- 加载
.infra/memory/constitution.md 进行原则验证
3. 构建语义模型
创建内部表示(输出中不包含原始制品):
- 需求清单: 每个功能和非功能需求, 带有稳定键(基于祈使短语推导 slug; 例如, "User can upload file" ->
user-can-upload-file)
- 用户故事/操作清单: 带有验收标准的离散用户操作
- 任务覆盖映射: 将每个任务映射到一个或多个需求或故事(通过关键词/显式引用模式推断, 如 ID 或关键短语)
- 章程规则集: 提取原则名称和 MUST/SHOULD 规范性声明
4. 检测过程(高效令牌分析)
专注于高信号发现. 限制总共 50 个发现; 在溢出摘要中聚合其余部分.
A. 重复检测
B. 模糊性检测
- 标记缺乏可测量标准的模糊形容词(快速、可扩展、安全、直观、稳健)
- 标记未解决的占位符(TODO、TKTK、???、
<placeholder> 等)
C. 规范不足
- 有动词但缺少对象或可测量结果的需求
- 缺少验收标准对齐的用户故事
- 引用规范/计划中未定义的文件或组件的任务
D. 章程对齐
- 与 MUST 原则冲突的任何需求或计划元素
- 章程中缺失的强制部分或质量门控
E. 覆盖缺口
- 没有关联任务的需求
- 没有映射需求/故事的任务
- 未在任务中反映的非功能需求(例如, 性能、安全性)
F. 不一致性
- 术语漂移(相同概念在不同文件中命名不同)
- 计划中引用但在规范中缺失的数据实体(反之亦然)
- 任务排序矛盾(例如, 集成任务在基础设置任务之前而没有依赖说明)
- 冲突需求(例如, 一个要求 Next.js 而另一个指定 Vue)
5. 严重性分配
使用此启发式方法对发现进行优先级排序:
- 严重: 违反章程 MUST、缺失核心规范制品, 或零覆盖的需求阻止基线功能
- 高: 重复或冲突需求、模糊的安全/性能属性、不可测试的验收标准
- 中: 术语漂移、缺失非功能任务覆盖、规范不足的边缘情况
- 低: 风格/措辞改进、不影响执行顺序的轻微冗余
6. 生成紧凑分析报告
每轮检测输出 Markdown 分析报告(不单独写入报告文件; 自动修复时对制品的编辑照常写入对应 spec.md / design.md / tasks.md), 结构如下:
规范分析报告
| ID | 类别 | 严重性 | 位置 | 摘要 | 建议 |
|---|
| A1 | 重复 | 高 | spec.md:L120-134 | 两个相似需求... | 合并表述; 保留更清晰的版本 |
(每个发现添加一行; 生成以类别首字母为前缀的稳定 ID.)
覆盖摘要表:
章程对齐问题:(如果有)
未映射任务:(如果有)
指标:
- 总需求数
- 总任务数
- 覆盖率%(有 >=1 个任务的需求)
- 模糊性计数
- 重复计数
- 严重问题计数
7. 自动修复与完成
- 不要询问用户是否修复、是否继续或是否采纳建议; 不要输出需用户选择的「下一步命令」交互块.
- 对可自动消除的问题（术语统一、任务与需求对齐、明显遗漏的子任务、与设计不一致的表述、章程冲突在制品层面的可消除项等）直接改文件.
- 每轮修改后重新执行本技能的分析检测（从步骤 3 起可增量）; 不设最大迭代轮数, 直至连续执行的一轮中已无可自动应用的修复（收敛）后退出修复循环.
- 结束输出: 输出完成摘要（累计修复要点、最终覆盖指标）; 若仍有残留问题, 须完整列出残留项（表格或清单, 含严重性）, 并明确声明本技能已正常完成, 后续步骤应继续执行, 不得将本阶段标为失败或中止 workflow.
8. 记录本skill的运行日志信息
执行runlog-record skill，请将前面获取到的start_time的值作为参数传入runlog-record skill
操作原则
上下文效率
- 最小高信噪比令牌: 专注于可操作的发现, 而不是详尽的文档
- 渐进式展示: 增量加载制品; 不要将所有内容倾倒到分析中
- 高效令牌输出: 限制发现表为 50 行; 总结溢出部分
- 确定性结果: 无更改重新运行应产生一致的 ID 和计数
分析指南
- 按上文对三制品做一致性修复; 绝不虚构缺失部分(如果缺失, 准确报告; 应通过显式补充条目或标注依赖来解决, 而非编造不存在的代码路径)
- 禁止以「仍有残留问题」为由输出失败状态、退出码式失败或阻断调用方; 残留问题仅通过报告列出, 本技能始终以正常完成收尾
- 优先处理章程违规(这些总是严重的)
- 使用示例而非详尽规则(引用具体实例, 而不是通用模式)
- 优雅报告零问题(发出带有覆盖统计的成功报告)
