CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

quality-gate

开发完成后的自检门禁:愿景对照 + spec 合规 + 验证。 Use when: 准备对交付作完成声明、需要整理风险匹配的自证。 Not for: 收到 review 反馈(用 receive-review)、merge(用 merge-gate)。 Output: Spec 合规报告(含愿景覆盖度)。

Quality

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./cat-cafe-skills/quality-gate/SKILL.md
SKILL.md
Quality
Evals
Security

SOP 位置: 本 skill 是 sop-definitions/development.yaml stage quality_gate 的执行细节。 SOP definition: sop-definitions/development.yaml stage quality_gate。 这是按需自检车道,不绑定固定上一步 / 下一步;完成后把证据交给实际选择的独立验证源或交付载体。

Quality Gate

完成声明前做两件事:对照真实需求自检,并用与风险面匹配的真实命令输出证明声明。

先理解本次答应交付的结果,再选择验证。需求仍是含糊愿望或不可承诺结果时,先澄清,不自行编 AC;已有清楚约定则沿用。原问题到交付的判断方法帮助核对实际使用场景,程序只检验可确定的行为,不能代替猫判断是否解决原问题。

核心知识

两条铁律合一:

  1. Spec alignment(来自 spec-compliance-check):AC 可能写偏,先回读原始需求,再逐项验收
  2. Evidence before claims(来自 verification-before-completion):没有运行命令、没看到输出,就不能说"通过了"

铁律:NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

自问:"我是这次真的运行了命令并看到输出,还是我只是相信它能工作?"

为什么 AC 可能不够:AC 是人写的,可能遗漏 UX 要求或场景覆盖。F041 教训:AC 全打勾,但operator的原始需求(能力显示描述、多项目管理)根本没进 AC——spec compliance check 检查了 AC,但 AC 本身就是错的。

流程

BEFORE 声称完成 / 提 review:

Step 0: VISION CHECK(愿景核对)
  ① 找原始 Discussion/Interview 文档(operator experience在里面)
  ② 读核心痛点:"我要..."、"我不想..."
  ③ 问自己:operator坐在 Hub 前用这个功能,体验是什么样的?
  ④ AC 是否完整覆盖了operator的原始需求?
     → 如有遗漏,先补 AC 再继续

Step 0.5: DELIVERY COMPLETENESS CHECK
  ① 这次交付的是完整 feat 还是 feat 的一部分?
     → 完整 feat:继续
     → 部分:有operator明确同意分批交付的记录吗?没有就继续做完
  ② 本次产出后续需要"重写"还是"扩展"?
     → 扩展:通过
     → 重写:如果是已标注 Spike 且有结论,通过;否则不通过,回去重做

Step 1: FIND — 找 spec/plan 文档
  - the active feature spec or implementation plan
  - 同时找 Discussion/Interview(operator experience所在)

Step 2: CREATE — 先确定完整旅程,再组织检查
  - 从原始需求写清本次约定的完整路径:从哪进、做什么、拿到什么结果,以及需要时怎样回到原处或再次打开
  - 将 AC / 功能点 / 关键边界挂在这条旅程下面;检查组合操作与真实接线,不把各按钮分别点通当作旅程走通
  - 按风险将计算、组件事件等局部分支交给单测或集成测试;浏览器检查真实入口、导航、渲染和跨步骤状态,不为每个内部切片重复验整套按钮
  - 非交互交付按其真实使用场景写输入、处理与最终结果;不为纯文档或内部计算虚构页面旅程

Step 2.5: CLOSE GATE MATRIX + FOLLOW-UP TAIL SCAN(F177 Phase A)🔴
  - **下面 CloseGateReport / unmet AC 处置 / tail scan / cvo_signoff 四项仅在本次交付声称关闭 Feature(feat close)时执行;普通 PR / Phase 内交付跳过这四项、不生成 CloseGateReport。本步其余按作者触发的检查(包装未做作者的 close 复核)不受此门线影响,仍按各自条件执行**
  - 检查 CloseGateReport 是否已生成(schema: `../.cat-cafe-shared-refs/close-gate.md`)
  - 每个 unmet AC 是否三选一处置(immediate / delete / cvo_signoff)
  - **Follow-up tail scan**:扫以下文本来源,命中关键词 = **线索(进入语义判定),不是自动 BLOCKED**——判定标准只有一条:该词是否在把 **unmet AC 包装成已完成 / 偷偷延期**(close 借口)。正常阶段描述("X 属 next phase 的 scope")、风险讨论、路线图引用不触发(2026-07-15 修订:raw keyword 自动 BLOCK 误杀正常文本):
    - 来源:close report、PR body、commit messages、spec 中 AC 注释、review 反馈回复
    - 线索关键词(不区分大小写;仅用于定位待语义检查处):
      `follow-up` `followup` `deferred` `next phase` `next PR` `P2` `stub` `TD`
      `后续` `留个尾巴` `先这样` `下次一定` `回头` `以后再` `will address later`
      `out of scope`(作为 close 借口时)`MVP 先上`(作为 close 借口时)
    - 豁免:spec 的 Why/Risk/History 章节中引用历史上下文时使用这些词不触发
  - cvo_signoff 四件套完整性验证(proposal + cvo message + quote + scope)
  - 🔴 **包装未做作者的 close 复核**(F177 Phase B,原为针对单只已退役猫的规则):仅当 PR 作者的 dossier「翻车熔断信号」写有「包装未做 / 过早收口」类失败模式时,其 feat close PR 的 quality-gate 由非作者猫重跑,按风险默认只选一只,同族也行;审核者由 reviewer/系统按当前 roster 指定,作者无选择权。其他作者照常自检。通用底线不变:作者自评不能替代已选择的独立 review(reviewer ≠ author)
  - **hotfix**(F177 Phase E):执行 `node scripts/check-hotfix-pattern.mjs` 识别 hotfix 模式;其"自我说服"风险由跨个体 review 铁律承接(reviewer ≠ author,merge-gate 校验),作者照常自检,不再额外安排另一只猫重跑 quality-gate

Step 2.6: FALLBACK LAYER CHECK(F177 Phase D)🔴
  - 执行:`node scripts/check-fallback-layers.mjs` 扫描 PR diff
  - 同一文件新增 ≥3 层 fallback 或累计 ≥5 层 → 触发坐标系自检
  - 自检三问:①修坐标系还是补错误坐标系?②坐标变换能否消除?③每层为什么不能去掉?
  - 层数合理时在报告中说明理由;不合理时重构后再过 gate

Step 2.7: ARCHITECTURE OWNERSHIP REPORT(F191,warning-only)🔴
  - 执行:`pnpm check:architecture-ownership`
  - 从 spec / plan 抄入:
    `Architecture cell` / `Map delta` / `Why`
  - 若缺失,报告 `⚠️ missing` 并列为 review focus;不在 quality-gate 做 semantic hard block
  - 若 `Map delta: none` 但 diff 明显新增 `Store|Queue|Router|Adapter|Dispatcher|Binding` 等架构名词,报告 mismatch 给 reviewer
  - 若 `Map delta: update required|new cell required`,报告对应 ownership cell / new cell 文件是否随 PR 更新
  - 注意:quality-gate 只报告机械可见事实;架构语义正确性由 Design Gate + reviewer 判断

Step 3: VERIFY — 逐项检查
  - 代码在哪?有测试覆盖?边界处理了?
  - 🔴 F244 Tips Contribution:若本 PR 新增/修改 user-visible feature / capability / guide / harness behavior,
    必须满足其一:
    ① `packages/web/src/lib/capability-tips.seed.json` 有对应 `sourceRef` tip
    ② 相关 feature/guide/skill 文件写明 `tips_exempt: {reason}`
    并执行 `pnpm check:capability-tips`。
    注意:CI 只证明结构/anchor/action;reviewer 仍要退回只复述标题、没有动作或时机的废话 tip。
  - 🔴 交付物必须核实 commit/PR 状态(git log --grep + gh pr list)
    spec checkbox 是记录工具,不是真相源(LL-029)
  - 🔴 新增 MCP 工具 → 认知入口更新了吗?优先级:MCP tool description → 相关 skill refs → capability wakeup / L0 quick index;只有 legacy/fallback surface 仍依赖时才补 `MCP_TOOLS_SECTION`(F086 教训:造了工具猫不知道;F203 后不再默认塞 SystemPromptBuilder)
  - 🔴 新增行为规则 → governance digest / shared-rules 注入更新了吗?
  - 🔴 产出了 SKILL.md 或改了 MCP tool description → 加载 `writing-skills`,用 T0 六要素审查质量(软硬同检)

Step 4: RUNTIME GUARD — 前端证据采集前先做运行态保护
  - 若会话在 `cat-cafe-runtime`,先探活:`curl -sf http://localhost:3004/health`
  - 服务已在线时直接复用,禁止在该会话执行 `pnpm start` / `pnpm runtime:start` / `pnpm runtime:restart` / `pnpm runtime:stop` / `./scripts/start-dev.sh`
  - `localhost:3003/3004` 默认按 runtime 处理;如果你要验证未合入改动,不能把这两个端口的页面/接口响应当成当前分支的证据
  - 证明“这是我当前 worktree 的验证证据”时,必须同时说清:`worktree/cwd` + 目标 URL。两者对不上 = 证据无效
  - 确需重启时,先获operator明确授权,再执行 `pnpm runtime:restart`;shell 参数与环境变量都不是授权证明
  - **Alpha 优先**:验证已合入 main 的改动时,优先用 `pnpm alpha:start`(3011/3012/4111/6397)取证,而非 runtime。Alpha 环境每次启动自动同步 origin/main

Step 4.5: DOGFOOD — 实际走通本次约定的完整旅程(F209 / F314)🔴
  对 user-visible / runtime feature,author 必须在请求 review 前:
    ① 实际走 Step 2 的完整旅程,从真实入口与输入到最终结果,覆盖需要的返回、保存与重进;不能用当前 slice 的局部成功代替原约定
      旅程的输入用需求方原话里的真实例子和真实数据(原话说"打开 backlog",就打开那份 backlog),不用作者自己挑的样例。原话里的核心动作用真实数据做不到,记"没走通",不记成小缺口或下一阶段。给猫用的功能,由一只猫在真实任务里实际调用一次;人和猫都用的能力,两边各走一遍,确认调用的是同一个底层操作。
    ② 把命令 + 输出 / 截图证据写进 Quality Gate Report 的 "Dogfood" 块
    ③ 抓到的任何 dogfood bug 必须当轮修,不允许"post-merge 再说"
    ④ **结构性例外**(2026-07-15):验证路径只在合入后才存在(需 main/alpha 环境或真实外部案例,AC-F7 型)→ pre-merge 验证到能验的边界即可,剩余由**带 owner + 触发条件的持久 post-merge task** 接走,**不阻塞 pre-merge review / merge**;若它是 required AC,则 task 在 terminal PASS(或 `delete` / `cvo_signoff`)前仍阻塞 **feature close**。例外理由写进 review packet

  Scope(必做 vs 可豁免):
    - **必做**:任何对最终用户 / 猫体感有变化的 feature 或 bugfix。包括但不限于:
      search / recall / UI / routing / drillDown / typed reader / 任何新 MCP tool / 任何新 REST 端点 /
      **任何修复用户或猫可感知路径的 bugfix(即使已有回归测试覆盖)**
      → 反例 PR #1854 dogfood hotfix:file-slice drillDown 路径口径不一致,已有回归测试也不够——
        必须 author 自己跑一遍 `search_evidence → drillDown → read_file_slice` 才能抓到
    - **可豁免**:docs-only / 纯重构 / 纯测试 / 内部基础设施 / **纯内部 bugfix(非 user/cat 可感知路径,如内部 DB 一致性、log format、纯算法常量调整等)**
      → 豁免必须**显式在 review packet 里写出理由**("docs-only" / "纯重构 + 既有测试覆盖" / "纯内部 bugfix,不影响 user/cat 可感知路径"等),不能省略

  Why(F209 反思 2026-05-23):
    "AC pass 但用户感受不到" + "dogfood bug post-merge 才暴露" 是同型走偏。
    - Phase B alias registry: AC-B1~B5 全 ✅、跨族 review APPROVE、merge 闭环 — 但生产 `entity_registry` 是空的,真实用户搜 `operator` 找不到 `operator`。
    - Phase C drillDown: 测试 / cloud review / merge 都过 — 但 author 自己 post-merge 用一次刚发现 file-slice 路径口径不一致。
    根因是没人 pre-review 真用一次自己刚做的东西。pre-merge dogfood 把这一类 bug 提前到 author 自检阶段。

  报告写法(在 Quality Gate Report 里加 "### Dogfood" 块):
    ```markdown
    ### 完整旅程(Dogfood)
    完整旅程:走通 / 没走通(断点:...)/ 不适用(本次交付与验证方式:...)
    Scope verdict: ✅ 必做 / 🆗 可豁免(理由:xxx)

    (必做时)
    实际使用路径: search_evidence("operator") → drillDown → cat_cafe_get_thread_context → 读到能回答原问题的原文
    实际命令 / 输出(粘贴): ...
    发现的 bug: 无 / 列表(含修复 commit SHA)
    ```

Step 5: 参考与实物对照 — 有产品/体验要求时
  先在 designs/ 中用 glob designs/**/*.pen 查设计稿,再沿 feature doc / 原讨论 / docs/evidence 查已接受的参考。
  命令帮助发现材料,猫判断哪些与本次任务相关;找到适用参考后,用同一任务核对本次实物。
  关注对象、操作位置、状态变化和结果;没有 .pen 不等于没有参考,更不等于可以跳过产品判断。
  比较方法按问题选择,不用文件后缀、截图数量或勾选代替判断。

Step 6: RUN — 运行风险匹配的验证命令(必须这次真实运行)
  ① 先列五轴风险与受影响面;命令逐条对应 claim,不按“写了代码”机械全跑
     测试增量先按 docs/ops/testing-standard.md 核真实失败、最低足够层级、已有覆盖缺口与成本;pass 数不代替判断
  ② 默认:受影响 package / schema / generator / docs checker + git diff --check
  ③ 新行为 / bug:相关行为或回归测试;现有精确检查红可以直接作 RED
  ④ targeted 无法覆盖实际风险时才跑 pnpm gate;作者可按 merge-gate「Gate 选择」带依据调整机器默认 full,保留按风险要求的独立审查和硬边界
  ⑤ Redis 相关改动额外跑:pnpm --filter @cat-cafe/api test:redis(租用隔离端口;保护 6397/6398/6399/6401)
  ⑥ 相关或尚未排除关联的红灯先修;已证实无关的失败保留并交原 owner,不阻塞自己的充分验证;不得隐去失败
     批量清理先收齐并完成成批修改,再集中验证;之后只为实质变化、新失败或未解决疑点补跑相关项

Step 7: READ — 完整读输出,看 exit code,数失败数

Step 7.5: ARTIFACT HYGIENE CHECK — 根目录媒体垃圾闸门
  - 执行(工作树):
    `git status --short | rg '^.. [^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 执行(已提交差异):
    `git diff --name-only origin/main...HEAD | rg '^[^/]+\.(png|jpe?g|webp|gif|webm|mp4|mov|wav|pdf|pen)$'`
  - 任一命中 → BLOCK:说明仓库根目录出现了媒体/设计工件(含已跟踪和未跟踪)
  - 处理方式:移到 `${TMPDIR}/cat-cafe-evidence/...` 或显式归档到正式目录后再继续
  - 规则真相源:`../.cat-cafe-shared-refs/evidence-output-contract.md`

Step 8: REPORT — 输出合规报告 + 证据

前端功能额外要求:author 必须在正确 worktree / preview 的真实入口走关键交互,并记录 URL、操作与结果。SOP 产品快车道先在第一小时争取交付实物、贴作者自采截图并对照原约定,不等 review/full 后才看;其余场景按判断需要选择截图、录屏、DOM assertion 或 Playwright 证据,不把缺截图转成 operator 的劳动。人工预览不以前置跑整套浏览器测试代替;合入后作者在 Alpha 核对。执行细则:../.cat-cafe-shared-refs/vision-evidence-workflow.md。

视觉对照的用法:需要判断布局和操作关系时,把已接受的参考与实际页面放在一起看,并实际操作关键状态。截图适合说明外观,不能单独证明保存、返回或恢复;已有证据仍覆盖的部分可以复用。有意偏离参考要说明真实原因,涉及新价值取舍时再找 operator,不要求用户重复批准同一方向。

2026-03-11 教训:三只Ragdoll同时跳过了已有 .pen 对照,所以保留命令驱动的参考发现。发现步骤不替猫判断设计,也不能用“没有 .pen”排除图片或实页等其他已接受参考。

Quick Reference

Claim需要不够用
测试通过这次运行输出:0 failures"上次跑过"、"应该通过"
targeted checks 通过与改动面对应的本轮命令 + exit 0只挑一盏绿灯、隐去相关红灯
full gate 通过影响范围要求 full 时本轮 pnpm gate exit 0凭风险标签机械全跑,或局部证据冒充 full
Bug 修了原症状测试:通过代码改了,以为修了
需求满足对照 spec / 原讨论判断实际使用结果,说明依据与未验证处测试通过或逐项打勾就完事
Feature 完成/未完成git log + PR 状态 + spec 逐项只看 spec checkbox 就下结论

合规报告模板:

## Quality Gate Report

完整旅程:走通 / 没走通(断点:...)/ 不适用(本次交付与验证方式:...)
Spec: feature spec or implementation note
原始需求: feature-discussions/YYYY-MM-DD-xxx/README.md
检查时间: YYYY-MM-DD HH:MM

### 愿景覆盖(Step 0)
| # | operator原始需求 | AC 覆盖? | 实现? |
|---|---------------|-----------|--------|
| 1 | "我要 XXX"    | AC#3      | ✅     |

### 旅程与支撑检查
约定路径:<真实入口、组合操作、最终结果;需要时包含返回与重进>
| 旅程环节 | 要求 / 关键边界 | 状态 | 代码位置 | 验证证据 |
|----------|-----------------|------|----------|----------|
| XXX      | XXX             | ✅   | file.ts:L10 | test.spec.ts / 实际操作 |

### 参考与实物对照(适用时)
已接受参考与实际路径:<来源 / 本次观察>
判断:<是否保留了约定的操作与结果;差异及理由>

### Artifact Hygiene(Step 7.5)
仓库根目录媒体/设计工件(工作树 + 已提交差异): 无 ✅

### Architecture Ownership(Step 2.7)
Architecture cell: dispatch
Map delta: none
Why: 只扩展现有 InvocationQueue 行为,不改变 dispatch cell 边界
Diff mismatch scan: 无新增并行 Store/Queue/Router/Adapter ✅

### 完整旅程(Step 4.5 Dogfood)
Scope verdict: ✅ 必做 / 🆗 可豁免(理由)
(必做时)实际路径与结果: <Step 2 的完整旅程,哪一步走通或断开>
实际命令 / 输出 / 截图: ...
发现的 bug: 无 / 列表(含修复 commit SHA)

### 五轴风险与验证命令(必须是这次真实运行)
风险: behavior=<...> data=<...> security=<...> contract=<...> irreversible=<...>
<targeted command 1> → exit 0 ✅(覆盖 claim: ...)
<targeted command 2> → exit 0 ✅(覆盖 claim: ...)
pnpm gate → exit 0 ✅(仅影响范围要求 full 时填写)

Common Mistakes

错误正确做法
只检查 AC,没回读 DiscussionStep 0 先读原始需求,AC 可能不完整
"上次跑测试是通过的"先问证据是否仍覆盖当前 HEAD 与输入:同 HEAD 同输入可复用并引用原始输出;变了只重跑受影响的检查
"应该没问题" / "probably works"Run the command. Read the output.
测试通过就声称 phase 完成还要对照 spec 逐项检查
部分实现就提 reviewP1/P2 遗漏必须当轮补完再提 review
交付半成品让operator"先看看"交付完整 feat,步骤是内部节奏不是交付批次
产出后续要重写而非扩展如果要重写,说明绕路了(Spike 除外)
author 没跑 frontend preview,把“缺截图”扔给 operatorauthor 走关键交互;按视觉风险选择截图 / 录屏 / DOM / 浏览器测试证据
没有 .pen 就跳过产品判断按原始来源查参考,结合实际使用判断,不由文件格式决定
为了截图在 runtime 会话里重跑 pnpm start先探活复用现有 runtime;确需重启必须显式授权
拿 runtime 的 3003/3004 页面当成当前 worktree 的验证结果报告里同时写明 pwd/worktree 和目标 URL;如果 URL 是 3003/3004,默认这是 runtime 证据,不是未合入改动证据
截图/录屏/设计稿顺手掉进仓库根目录Step 7.5 必查;先移到 ${TMPDIR}/cat-cafe-evidence/... 或正式归档目录,再继续
Redis 改动用默认测试命令必须跑 test:redis,禁止直连 6399
产出了 skill/MCP 但没审查质量加载 writing-skills,用 T0 六要素审查(软硬同检)
只看 spec checkbox 就声称完成/未完成核实 git log --grep + gh pr list + 实际 commit(LL-029)
功能项全绿,却没走通原来的事Step 2 先确定完整旅程,Step 4.5 真正走一遍;局部成功不代替完整结果,按实际风险复用仍有效的证据

Red flags — 立刻 STOP:

  • 用 "should"、"probably"、"seems to"
  • 表达满足感("好了!"、"完成!")时还没运行命令
  • 信任 subagent 的 "success" 报告而没独立验证

和其他 skill 的区别

Skill关注点时机
quality-gate(本 skill)spec 对照 + 风险匹配证据作完成声明之前
merge-gate选定验证是否足够、适用 review 是否放行、P1/P2 是否全修合入 main 之前
receive-review如何处理 reviewer 的反馈收到 review 之后

quality-gate 负责作者自检,merge-gate 消费风险匹配的交付证据,receive-review 处理已收到的审查意见。

下一步

Quality Gate 通过后,符合 docs/SOP.md 产品快车道且未选 review 的改动由作者直接进入 merge-gate;其余把证据交给风险路由已选择的独立验证源:治理 / stateful 语义通常走 request-review;安全 / 契约的 context-blind 扫描可走 cloud;fresh-context-review 仅在 author 判断认知盲点收益足够时作为 finding generator,不是固定前置。

Gate 未通过时:

  • P1 遗漏 → 补完再过 gate
  • P2 遗漏 → 必须当轮补完再提 review
  • 检查失败 → 修复相关失败;已证实无关的失败交原 owner,作者按 merge-gate 的验证裁量完成自身覆盖后继续交付
Repository

zts212653/clowder-ai

Path

cat-cafe-skills/quality-gate/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.