用途
Quality Gates 是一个面向 AI 智能体的技能，用于在开始复杂任务前评估任务复杂度、执行质量门禁检查，并防止在不完整或定义不清的任务上浪费工作。其核心原则是：在信息不完整时先停下来澄清，宁可提问也不要浪费周期在错误的解决方案上。
主要能力
复杂度评分（1-5 级）
技能提供一套复杂度评分标准，依据文件数、代码行数、耗时、依赖数量与未知因素划分等级：
- Level 1 - Trivial：1 个文件，< 50 行，< 30 分钟，无依赖、无未知
- Level 2 - Simple：1-3 个文件，50-200 行，30 分钟 - 2 小时，0-1 个依赖，极少未知
- Level 3 - Moderate：3-10 个文件，200-500 行，2-8 小时，2-3 个依赖，部分未知
- Level 4 - Complex：10-25 个文件，500-1500 行，8-24 小时，4-6 个依赖，显著未知
- Level 5 - Very Complex：25+ 个文件，1500+ 行，24+ 小时，7+ 个依赖，大量未知
评分采用 max(file_count, LOC, dependency_count, unknowns)，而非平均值：只要有一个维度达到 Level 5，任务即为 Level 5。可通过 scripts/assess-complexity.md 或 scripts/analyze-codebase.sh <target> 测量输入。
阻塞阈值
技能定义了以下门禁条件：
- YAGNI 门禁：合理比率 > 2.0 时 BLOCK，并给出更简单的替代方案
- YAGNI 警告：合理比率 1.5-2.0 时 WARN，并给出更简单的替代方案
- 关键问题：超过 3 个未回答时 BLOCK
- 缺失依赖：任何阻塞性依赖时 BLOCK
- 失败尝试：>= 3 次时 BLOCK 并升级
- 证据失败：2 次修复尝试后 BLOCK
- 复杂度溢出：Level 4-5 且无计划时 BLOCK
WARNING 条件（谨慎继续）：Level 3 复杂度、1-2 个未回答问题、1-2 次失败尝试。
门禁决策流程
- YAGNI 检查（最先运行，在任何实现规划之前）：读取项目层级，计算 justified_complexity = planned_LOC / tier_appropriate_LOC；比率 > 2.0 则 BLOCK（必须简化）；比率 1.5-2.0 则 WARN（给出更简单替代方案）；安全模式豁免于 YAGNI 门禁。
- 评估复杂度（1-5）
- 统计未回答的关键问题数
- 检查被阻塞的依赖
- 检查尝试次数
决策逻辑：若 yagni_ratio > 2.0 则 BLOCK；否则若 questions > 3 或 deps blocked 或 attempts >= 3 则 BLOCK；否则若 complexity >= 4 且无计划则 BLOCK；否则若 yagni_ratio > 1.5 或 complexity == 3 或 questions 为 1-2 则 WARNING；否则 PASS。
模板与集成
技能提供门禁检查模板（记录复杂度、未回答关键问题、阻塞依赖、失败尝试、状态与是否可继续）和升级模板（记录任务、阻塞类型、尝试次数、已尝试方案及失败原因、需要指导的问题、建议行动）。
集成方面，提供与上下文系统的集成示例（将门禁检查结果推入 context.quality_gates）以及与证据系统的集成示例（在标记任务完成前检查测试或构建的 exit_code 是否为 0，否则返回 blocked）。
模式库与最佳实践
技能包含模式库，跨项目跟踪成功/失败模式，防止重复错误并在代码审查中主动预警。规则文件包括：YAGNI Gate（rules/yagni-gate.md）、Pattern Library（rules/practices-code-standards.md）、Review Checklist（rules/practices-review-checklist.md）。模式置信度分为：强成功（3+ 项目、100% 成功，始终推荐）、混合结果（视上下文而定）、强反模式（3+ 项目全部失败，阻塞并解释）。
常见陷阱
- 对“简单”任务跳过门禁：后续会卡住，应始终运行门禁检查
- 忽略 WARNING 状态：未记录的假设会引发问题，应记录每个假设
- 不跟踪尝试次数：会在同一方法上浪费周期，应跟踪每次尝试并在 3 次时升级
- 在 BLOCKED 时继续：会构建错误方案，绝不应绕过 BLOCKED 门禁
使用方式
技能支持自动激活与手动激活。
自动激活触发条件：接收新任务分配、开始复杂功能实现、在 Squad 模式中分配工作前、需求不清或不完整时、同一任务失败 3 次后、被依赖阻塞时。
手动激活：用户要求复杂度评估、规划多步骤项目、承诺时间线之前。
按需加载参考文件：使用 Read("references/<file>") 加载，包括 ork-delta.md（OrchestKit 特定经验与内部决策）和 unified-scoring-framework.md（0-10 维度、权重、等级阈值、改进优先级）。
适用场景
适用于 AI 智能体在任务开始前进行复杂度评估与门禁检查、在需求不清时决定是否阻塞、在多次失败后决定是否升级、在代码审查中对照最佳实践、以及在 Squad 模式中分配工作前进行质量把关。
限制
技能文档中明确说明：部分主题不在本技能内重复讲授，而是指向上游来源，包括复杂度评分标准、阻塞与警告条件、升级协议、YAGNI 比率与项目层级 LOC 预算、评分维度与权重、LLM-as-judge 模式、需求完整性模板、测试标准、仓库指标、LangGraph 条件路由、FastAPI 错误响应、Pydantic 验证器、重试与 SLO 告警等。本技能仅保留 OrchestKit 特有的增量内容。