quality-gates

质量门禁

此技能教 Agent 如何评估任务复杂度、执行质量门禁，并避免在任务不完整或定义不清时浪费精力。

核心原则： 信息不完整时，应先暂停并澄清，再继续推进。与其把精力浪费在错误的解决方案上，不如先提出问题。

---

概述

自动激活触发条件

• 收到新的任务分配
• 开始实现复杂功能
• 在 Squad 模式下分配工作之前
• 需求看起来不明确或不完整时
• 同一任务连续失败 3 次后
• 被依赖项阻塞时

手动激活

• 用户要求评估复杂度
• 规划多步骤项目
• 确定时间表之前

---

核心概念

复杂度评分（1-5 级）

级别	文件数	行数	时间	特征
1 - 微不足道	1	< 50	< 30 分钟	无依赖项、无未知情况
2 - 简单	1-3	50-200	30 分钟 - 2 小时	0-1 个依赖项，未知情况极少
3 - 中等	3-10	200-500	2-8 小时	2-3 个依赖项，存在一些未知情况
4 - 复杂	10-25	500-1500	8-24 小时	4-6 个依赖项，存在显著未知情况
5 - 非常复杂	25+	1500+	24+ 小时	7+ 个依赖项，存在许多未知情况

上表是标准评分准则。评分时使用 max(file_count, LOC, dependency_count, unknowns)，而不是取平均值：任何一个维度达到 5 级，任务就属于 5 级。运行 scripts/assess-complexity.md 或 scripts/analyze-codebase.sh <target> 来测量各项指标。

阻断阈值

条件	阈值	操作
YAGNI 门禁	合理化比率 > 2.0	阻断，并提供更简单的替代方案
YAGNI 警告	合理化比率为 1.5-2.0	发出警告，并提供更简单的替代方案
关键问题	未回答的问题 > 3 个	阻断
缺少依赖项	存在任何阻塞项	阻断
失败尝试	>= 3 次	阻断并升级处理
证据失败	尝试修复 2 次	阻断
复杂度超限	4-5 级且没有计划	阻断

警告条件（谨慎继续）：

• 复杂度为 3 级
• 有 1-2 个未回答的问题
• 失败尝试 1-2 次

升级处理流程和门禁决策逻辑都在下方的“快速参考”中。YAGNI 比率、各级代码行数预算，以及更简单替代方案的展示规则见 rules/yagni-gate.md。

---

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
ork-delta.md	OrchestKit 专属经验与内部决策：行数统计准确性、失败时放行策略、门禁自我监控、不可绕过的类别
unified-scoring-framework.md	标准 0-10 维度、权重、等级阈值、改进优先级。ork:assess 和 ork:verify 也会加载此文件

---

上游内容覆盖范围（不要重复说明）

此技能封装了通用质量门实践，仅保留 OrchestKit 的差异内容。遇到以下主题时，请查阅对应来源，而不要在此处重新讲解。

主题	来源
复杂度 1-5 评分标准、各级示例、评估公式	上方的“复杂度评分”表，为权威来源
阻塞与警告条件、升级协议、尝试次数跟踪	上方的“阻塞阈值”和“快速参考”，为权威来源
YAGNI 比率、项目层级 LOC 预算、更简单的替代方案	rules/yagni-gate.md + ork:scope-appropriate-architecture
评分维度、权重、等级阈值	references/unified-scoring-framework.md
LLM-as-judge、G-Eval、方面评分、指标 API	ork:testing-llm
需求完整性、验收标准模板	ork:write-prd
作为质量门一部分强制执行的测试标准	ork:architecture-patterns
作为质量门输入的仓库指标（文件、LOC、测试、变更频率）	此技能中的 scripts/analyze-codebase.sh
质量门节点的 LangGraph 条件路由	https://langchain-ai.github.io/langgraph/
质量门失败时的 FastAPI 错误响应	https://fastapi.tiangolo.com/tutorial/handling-errors/
质量门输出架构的 Pydantic 验证器	https://docs.pydantic.dev/latest/concepts/validators/
指数退避重试、基于 SLO 的质量门告警	https://sre.google/workbook/alerting-on-slos/

---

快速参考

质量门决策流程

0. YAGNI check (runs FIRST — before any implementation planning)
   → Read project tier from scope-appropriate-architecture
   → Calculate justified_complexity = planned_LOC / tier_appropriate_LOC
   → If ratio > 2.0: BLOCK (must simplify)
   → If ratio 1.5-2.0: WARN (present simpler alternative)
   → Security patterns exempt from YAGNI gate

1. Assess complexity (1-5)
2. Count critical questions unanswered
3. Check dependencies blocked
4. Check attempt count

if (yagni_ratio > 2.0) -> BLOCK with simpler alternatives
else if (questions > 3 || deps blocked || attempts >= 3) -> BLOCK
else if (complexity >= 4 && no plan) -> BLOCK
else if (yagni_ratio > 1.5 || complexity == 3 || questions 1-2) -> WARNING
else -> PASS

质量门检查模板

## Quality Gate: [Task Name]

**Complexity:** Level [1-5]
**Unanswered Critical Questions:** [Count]
**Blocked Dependencies:** [List or None]
**Failed Attempts:** [Count]

**Status:** PASS / WARNING / BLOCKED
**Can Proceed:** Yes / No

升级模板

## Escalation: Task Blocked

**Task:** [Description]
**Block Type:** [Critical Questions / Dependencies / Stuck / Evidence]
**Attempts:** [Count]

### What Was Tried
1. [Approach 1] - Failed: [Reason]
2. [Approach 2] - Failed: [Reason]

### Need Guidance On
- [Specific question]

**Recommendation:** [Suggested action]

---

与上下文系统集成

// Add gate check to context
context.quality_gates = context.quality_gates || [];
context.quality_gates.push({
  task_id: taskId,
  timestamp: new Date().toISOString(),
  complexity_score: 3,
  gate_status: 'pass', // pass, warning, blocked
  critical_questions_count: 1,
  unanswered_questions: 1,
  dependencies_blocked: 0,
  attempt_count: 0,
  can_proceed: true
});

与证据系统集成

// Before marking task complete
const evidence = context.quality_evidence;
const hasPassingEvidence = (
  evidence?.tests?.exit_code === 0 ||
  evidence?.build?.exit_code === 0
);

if (!hasPassingEvidence) {
  return { gate_status: 'blocked', reason: 'no_passing_evidence' };
}

---

最佳实践模式库

跟踪各项目中的成功与失败模式，避免重复犯错，并在代码审查期间主动发出警告。

规则	文件	关键模式
YAGNI 质量门	rules/yagni-gate.md	实施前范围检查、合理的复杂度比率、更简单的替代方案
模式库	rules/practices-code-standards.md	成功/失败跟踪、置信度评分、记忆集成
审查清单	rules/practices-review-checklist.md	基于类别的审查、主动检测反模式

模式置信度级别

级别	含义	操作
强成功	3+ 个项目，成功率 100%	始终推荐
结果不一	既有成功也有失败	视上下文而定
强反模式	3+ 个项目，全部失败	阻止并说明原因

---

常见陷阱

陷阱	问题	解决方案
对“简单”任务跳过质量门	后续陷入困境	始终运行质量门检查
忽略警告状态	未记录的假设会引发问题	记录每一项假设
不跟踪尝试次数	在相同方法上浪费周期	跟踪每次尝试，在第 3 次时升级
受阻时仍继续	构建出错误的解决方案	绝不可绕过受阻的质量门

---

---

相关技能

• ork:scope-appropriate-architecture - 检测为 YAGNI 质量门提供依据的项目层级
• ork:architecture-patterns - 将测试标准作为质量门的一部分强制执行
• ork:testing-llm - 用于质量验证的 LLM-as-judge 模式（DeepEval、RAGAS）
• ork:golden-dataset - 验证数据集是否达到质量阈值

关键决策

决策	选择	理由
复杂度量表	1-5 级	细致程度足以用于估算，同时足够简单，便于快速评估
阻塞阈值	3 个关键问题	防止在存在过多未知事项时继续推进
升级触发条件	3 次失败尝试	在坚持与避免浪费周期之间取得平衡
4-5 级要求	必须制定计划	复杂任务需要预先拆解

功能详情

complexity-scoring

关键词： complexity、score、difficulty、estimate、sizing、1-5 scale 解决： 这项任务有多复杂？按 1-5 级为任务复杂度评分，评估实现难度

blocking-thresholds

关键词： blocking、threshold、gate、stop、escalate、cannot proceed 解决： 何时应阻止进展？>3 个关键问题 = BLOCK，缺少依赖项 = BLOCK

critical-questions

关键词： critical questions、unanswered、unknowns、clarify 解决： 什么是关键问题？统计未回答的问题，超过 3 个则阻止进展

stuck-detection

关键词： stuck、failed attempts、retry、3 attempts、escalate 解决： 如何检测陷入困境？失败 3 次后升级处理

gate-validation

关键词： validate、gate check、pass、fail、gate status 解决： 如何验证质量关卡？运行任务前关卡验证

pre-task-gate-check

关键词： pre-task、before starting、can proceed 解决： 如何在开始前检查关卡？评估复杂度，识别阻碍因素

complexity-breakdown

关键词： breakdown、decompose、subtasks、split task 解决： 如何拆解复杂任务？将 Level 4-5 的任务拆分为 Level 1-3 的子任务

requirements-completeness

关键词： requirements、incomplete、acceptance criteria 解决： 仅检查关卡：需求集是否足够完整，可以开始？需求编写本身属于 ork:write-prd（参见上游覆盖范围）

escalation-protocol

关键词： escalate、ask user、need help、human guidance 解决： 何时以及如何升级处理？失败 3 次后升级处理

llm-as-judge

关键词： llm as judge、g-eval、aspect scoring、quality validation 解决： 仅检查关卡阈值：评判器必须返回多少分才能通过？评判器的构建和运行属于 ork:testing-llm（参见上游覆盖范围）

yagni-gate

关键词： yagni、over-engineering、justified complexity、scope check、too complex、simplify 解决： 这种复杂度是否合理？根据项目等级计算 justified_complexity 比率，若 > 2.0 则阻止进展，并提出更简单的替代方案