create-request 是 sd0x-harness 提供的一个技能,用于创建、更新或扫描按任务划分的请求工单(request tickets),以跟踪任务进度。这些工单是 requests/ 目录下带日期前缀的非生命周期文档,并非功能级需求文档。
【用途与定位】 请求工单是从 /tech-spec 派生出的工作分解单元,本身不是需求文档。它们属于不同的文档类别:工单为带日期前缀的非生命周期文档(requests/YYYY-MM-DD-*.md),而 /req-analyze 产出的是生命周期文档(Phase 1,数字前缀 1-requirements.md)。每个功能可以有多个工单(每个任务一个),而需求文档每个功能只有一份。工单位于工作流的执行阶段(/tech-spec 之后),内容聚焦执行——状态、进度、验收标准清单、相关文件;需求文档位于设计阶段(/tech-spec 之前),聚焦问题空间——5-Why、FR/NFR、MoSCoW、利益相关者。
工作流顺序为:/req-analyze(Phase 1)→ /tech-spec(Phase 2)→ /create-request(每个任务一张工单)→ /feature-dev(实现)。工单会引用其父级 /tech-spec 获取技术细节,并可选链接到 1-requirements.md 获取问题空间依据。
【主要能力与模式】 该技能提供四种模式:
- create(默认):未指定文件或新建请求时,收集信息 → 填充模板 → 创建文件。
- update:指定文件或更新请求时,读取当前状态 → 检查实现 → 更新进度。
- update-all:使用 --update-all 标志时,批量扫描 → git 验证 → 更新所有过期文档 → 报告。
- scan:使用 --status 标志时,扫描所有请求 → 解析元数据 → 筛选未完成项 → 报告。
参数方面,--verify-ac 适用于单个 --update,会派发 Explore 智能体以证据(file:line)验证验收标准完成情况,支持通过功能上下文五级级联自动检测路径,但不能与 --update-all 一起使用。
【粒度检查】 创建模式中包含粒度检查阶段,评估请求是否应拆分为多个聚焦工单。检测信号包括:验收标准数量超过 8(主要)、层级混合(主要)、范围广度(需求含 3 个以上功能独立区域,主要)、WBS 分组 ≥ 2(次要,×0.5)、工作量超过 3 天(次要,×0.5)。信号计数 = 主要计数 + 0.5 × 次要计数;小于 2 则作为单个请求继续,大于等于 2 则建议拆分。
【验收标准计数规则】 验收标准是 ## Acceptance Criteria 章节内的顶层连字符任务列表项(实时文档文本)。缩进有界:段落下的更深缩进是段落延续,不算验收标准。围栏代码块、HTML 注释或缩进代码示例中的复选框是说明而非验收标准。部分工单以 AC → 证据表形式记录验收标准,这是有效形式但无法被这些路径计数。
【质量门验收标准分类器】 该分类器仅用于显示和粒度判断,不涉及状态推导。仅两条路径使用它:扫描模式的 AC 进度(仪表盘显示内容)和 Phase 1.5 的拆分信号。只有当验收标准是“回执”(receipt)时才算质量门——其内容是某个门已运行或为何未运行。回执标记包括:回执词(Pass/Passed/passes/通過)、round N 引用、破折号后的命名裁决哨兵(✅ PASS / ✅ Ready / ✅ Mergeable / ⛔ Blocked / ⛔ Needs revision / ❌ FAIL)、门生命周期尾部(superseded 或 pending 后跟有界窗口内的 round N 或裁决引用,或 tracked below)。
【不应使用的场景】
- 功能级需求分析(使用 /req-analyze)
- 查看请求结构(使用 request-tracking)
- 编写技术规格(使用 /tech-spec)
- 代码开发(使用 feature-dev)
【应避免的反模式】
- 在请求工单内写 5-Why / 利益相关者分析(应放入 1-requirements.md)
- 向 1-requirements.md 添加 ## Progress / ## Status 表(进度跟踪属于请求工单)
- 为整个功能创建一张请求工单(验收标准 > 8 时应拆分)
- 将 1-requirements.md 视为创建请求的前提(它仅为建议性,仅有 tech-spec 时请求也可独立工作)
【限制】 分类器使用正则表达式对自由文本验收标准进行分类,本质上是近似的,存在已知残留(published regex 比描述更宽松)。分类器失败时倾向于保留实质性内容——当验收标准确实模糊时予以保留。由于分类器不再影响状态,任一错误的代价仅是显示数字或建议性拆分信号,而非生命周期决策。