quality-gates

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quality Gates

质量关卡

This skill teaches agents how to assess task complexity, enforce quality gates, and prevent wasted work on incomplete or poorly-defined tasks.

Key Principle: Stop and clarify before proceeding with incomplete information. Better to ask questions than to waste cycles on the wrong solution.

本技能指导Agent如何评估任务复杂度、执行质量关卡检查，避免在不完整或定义模糊的任务上浪费精力。

核心原则： 信息不完整时先暂停并澄清。与其在错误的解决方案上浪费时间，不如主动提问。

Overview

概述

Auto-Activate Triggers

自动触发条件

Receiving a new task assignment
Starting a complex feature implementation
Before allocating work in Squad mode
When requirements seem unclear or incomplete
After 3 failed attempts at the same task
When blocked by dependencies

收到新任务分配时
启动复杂功能实现前
在Squad模式下分配工作前
需求看起来不清晰或不完整时
同一任务尝试3次失败后
被依赖项阻塞时

Manual Activation

手动触发方式

User asks for complexity assessment
Planning a multi-step project
Before committing to a timeline

用户要求进行复杂度评估时
规划多步骤项目时
承诺交付时间前

Core Concepts

核心概念

Complexity Scoring (1-5 Scale)

复杂度评分（1-5级）

Level	Files	Lines	Time	Characteristics
1 - Trivial	1	< 50	< 30 min	No deps, no unknowns
2 - Simple	1-3	50-200	30 min - 2 hr	0-1 deps, minimal unknowns
3 - Moderate	3-10	200-500	2-8 hr	2-3 deps, some unknowns
4 - Complex	10-25	500-1500	8-24 hr	4-6 deps, significant unknowns
5 - Very Complex	25+	1500+	24+ hr	7+ deps, many unknowns

See:

references/complexity-scoring.md

for detailed examples and assessment formulas.

等级	文件数	代码行数	耗时	特征
1 - Trivial（极简单）	1	< 50	< 30分钟	无依赖项，无未知因素
2 - Simple（简单）	1-3	50-200	30分钟 - 2小时	0-1个依赖项，极少未知因素
3 - Moderate（中等）	3-10	200-500	2-8小时	2-3个依赖项，存在部分未知因素
4 - Complex（复杂）	10-25	500-1500	8-24小时	4-6个依赖项，存在大量未知因素
5 - Very Complex（极复杂）	25+	1500+	24小时以上	7个以上依赖项，存在诸多未知因素

参考：

references/complexity-scoring.md

获取详细示例和评估公式。

Blocking Thresholds

阻塞阈值

Condition	Threshold	Action
YAGNI Gate	Justified ratio > 2.0	BLOCK with simpler alternatives
YAGNI Warning	Justified ratio 1.5-2.0	WARN with simpler alternatives
Critical Questions	> 3 unanswered	BLOCK
Missing Dependencies	Any blocking	BLOCK
Failed Attempts	>= 3	BLOCK & ESCALATE
Evidence Failure	2 fix attempts	BLOCK
Complexity Overflow	Level 4-5 no plan	BLOCK

WARNING Conditions (proceed with caution):

Level 3 complexity
1-2 unanswered questions
1-2 failed attempts

See:

references/blocking-thresholds.md

for escalation protocols and decision logic.

条件	阈值	操作
YAGNI关卡	合理性比值 > 2.0	阻止并提供更简单的替代方案
YAGNI警告	合理性比值 1.5-2.0	警告并提供更简单的替代方案
关键问题	未解决问题 > 3个	阻止
缺失依赖项	存在任何阻塞性依赖	阻止
失败尝试次数	>= 3次	阻止并升级
验证失败	2次修复尝试失败	阻止
复杂度溢出	4-5级复杂度且无计划	阻止

警告条件（需谨慎推进）：

3级复杂度
1-2个未解决问题
1-2次失败尝试

参考：

references/blocking-thresholds.md

获取升级协议和决策逻辑。

References

参考资料

Complexity Scoring

复杂度评分

See:

references/complexity-scoring.md

Key topics covered:

Detailed Level 1-5 characteristics and examples
Quick assessment formula
Assessment checklist

参考：

references/complexity-scoring.md

涵盖核心主题：

1-5级的详细特征和示例
快速评估公式
评估检查清单

Blocking Thresholds & Escalation

阻塞阈值与升级

See:

references/blocking-thresholds.md

Key topics covered:

BLOCKING vs WARNING conditions
Escalation protocol and message templates
Gate decision logic
Attempt tracking

参考：

references/blocking-thresholds.md

涵盖核心主题：

阻止条件 vs 警告条件
升级协议和消息模板
关卡决策逻辑
尝试次数追踪

Quality Gate Workflows

质量关卡工作流

See:

references/workflows.md

Key topics covered:

Pre-task gate validation workflow
Stuck detection and escalation workflow
Complexity breakdown workflow (Level 4-5)
Requirements completeness check

参考：

references/workflows.md

涵盖核心主题：

任务前关卡验证工作流
陷入困境检测与升级工作流
复杂度拆解工作流（4-5级）
需求完整性检查

Gate Patterns

关卡模式

See:

references/gate-patterns.md

Key topics covered:

Gate validation process templates
Integration with context system
Common pitfalls

参考：

references/gate-patterns.md

涵盖核心主题：

关卡验证流程模板
与上下文系统的集成
常见陷阱

LLM Quality Validation

LLM质量验证

See:

references/llm-quality-validation.md

Key topics covered:

LLM-as-judge patterns
Quality aspects (relevance, depth, coherence, accuracy, completeness)
Fail-open vs fail-closed strategies
Graceful degradation patterns
Triple-consumer artifact design

参考：

references/llm-quality-validation.md

涵盖核心主题：

LLM-as-judge模式
质量维度（相关性、深度、连贯性、准确性、完整性）
故障开放 vs 故障关闭策略
优雅降级模式
三重消费者工件设计

Quick Reference

快速参考

Gate Decision Flow

关卡决策流程

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

0. YAGNI检查（最先执行 — 在任何实现规划之前）
   → 从scope-appropriate-architecture中读取项目层级
   → 计算合理性复杂度 = 计划代码行数 / 对应层级的合理代码行数
   → 若比值 > 2.0：阻止（必须简化）
   → 若比值 1.5-2.0：警告（提供更简单的替代方案）
   → 安全模式不受YAGNI关卡限制

1. 评估复杂度（1-5级）
2. 统计未解决的关键问题数量
3. 检查依赖项是否阻塞
4. 检查尝试次数

if (yagni_ratio > 2.0) -> 阻止并提供更简单的替代方案
else if (questions > 3 || deps blocked || attempts >= 3) -> 阻止
else if (complexity >= 4 && no plan) -> 阻止
else if (yagni_ratio > 1.5 || complexity == 3 || questions 1-2) -> 警告
else -> 通过

Gate Check Template

关卡检查模板

markdown

undefined

markdown

undefined

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

undefined

复杂度： [1-5]级 未解决关键问题： [数量] 阻塞依赖项： [列表或无] 失败尝试次数： [数量]

状态： 通过 / 警告 / 阻止 是否可推进： 是 / 否

undefined

Escalation Template

升级模板

markdown

undefined

markdown

undefined

Escalation: Task Blocked

升级：任务被阻止

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

任务： [描述] 阻塞类型： [关键问题 / 依赖项 / 陷入困境 / 验证失败] 尝试次数： [数量]

What Was Tried

已尝试的方案

[Approach 1] - Failed: [Reason]
[Approach 2] - Failed: [Reason]

[方案1] - 失败原因：[原因]
[方案2] - 失败原因：[原因]

Need Guidance On

需要指导的内容

[Specific question]

Recommendation: [Suggested action]

---

[具体问题]

建议： [建议行动]

---

Integration with Context System

与上下文系统集成

javascript

// 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
});

javascript

// 向上下文添加关卡检查记录
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
});

Integration with Evidence System

与验证系统集成

javascript

// 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' };
}

javascript

// 标记任务完成前
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' };
}

Best Practices Pattern Library

最佳实践模式库

Track success/failure patterns across projects to prevent repeating mistakes and proactively warn during code reviews.

Rule	File	Key Pattern
YAGNI Gate	`rules/yagni-gate.md`	Pre-implementation scope check, justified complexity ratio, simpler alternatives
Pattern Library	`rules/practices-code-standards.md`	Success/failure tracking, confidence scoring, memory integration
Review Checklist	`rules/practices-review-checklist.md`	Category-based review, proactive anti-pattern detection

跨项目追踪成功/失败模式，避免重复犯错，并在代码评审时主动发出警告。

规则	文件	核心模式
YAGNI关卡	`rules/yagni-gate.md`	实现前范围检查、合理性复杂度比值、更简单的替代方案
模式库	`rules/practices-code-standards.md`	成功/失败追踪、信心评分、记忆集成
评审检查清单	`rules/practices-review-checklist.md`	基于类别的评审、主动检测反模式

Pattern Confidence Levels

模式信心等级

Level	Meaning	Action
Strong success	3+ projects, 100% success	Always recommend
Mixed results	Both successes and failures	Context-dependent
Strong anti-pattern	3+ projects, all failed	Block with explanation

等级	含义	操作
强成功	3个以上项目，100%成功	始终推荐
混合结果	既有成功也有失败	视上下文而定
强反模式	3个以上项目，全部失败	阻止并给出解释

Common Pitfalls

常见陷阱

Pitfall	Problem	Solution
Skip gates for "simple" tasks	Get stuck later	Always run gate check
Ignore WARNING status	Undocumented assumptions cause issues	Document every assumption
Not tracking attempts	Waste cycles on same approach	Track every attempt, escalate at 3
Proceed when BLOCKED	Build wrong solution	NEVER bypass BLOCKED gates

陷阱	问题	解决方案
为"简单"任务跳过关卡	后续陷入困境	始终执行关卡检查
忽略警告状态	未记录的假设引发问题	记录所有假设
未追踪尝试次数	在同一方案上浪费时间	追踪每一次尝试，3次后升级
被阻止时仍继续推进	构建错误的解决方案	绝对不要绕过被阻止的关卡

Version History

版本历史

v1.3.0 - Added YAGNI gate as Step 0 in gate flow, justified complexity ratio (BLOCK > 2.0, WARN 1.5-2.0), scope-appropriate-architecture integration

v1.1.0 - Added LLM-as-judge quality validation, retry logic, graceful degradation, triple-consumer artifact design

v1.0.0 - Initial release with complexity scoring, blocking thresholds, stuck detection, requirements checks

Remember: Quality gates prevent wasted work. Better to ask questions upfront than to build the wrong solution. When in doubt, BLOCK and escalate.

v1.3.0 - 在关卡流程中添加YAGNI关卡作为第0步，新增合理性复杂度比值（>2.0时阻止，1.5-2.0时警告），集成scope-appropriate-architecture

v1.1.0 - 添加LLM-as-judge质量验证、重试逻辑、优雅降级、三重消费者工件设计

v1.0.0 - 初始版本，包含复杂度评分、阻塞阈值、困境检测、需求检查

谨记： 质量关卡可避免工作浪费。与其事后返工，不如提前提问。如有疑问，直接阻止并升级。

Related Skills

Key Decisions

关键决策

Decision	Choice	Rationale
Complexity Scale	1-5 levels	Granular enough for estimation, simple enough for quick assessment
Block Threshold	3 critical questions	Prevents proceeding with too many unknowns
Escalation Trigger	3 failed attempts	Balances persistence with avoiding wasted cycles
Level 4-5 Requirement	Plan required	Complex tasks need upfront decomposition

决策	选择	理由
复杂度等级	1-5级	足够精细以支持估算，同时简单易快速评估
阻塞阈值	3个关键问题	避免在未知因素过多的情况下推进
升级触发条件	3次失败尝试	在坚持与避免浪费时间之间取得平衡
4-5级任务要求	必须有计划	复杂任务需要提前拆解

Capability Details

能力详情

complexity-scoring

Keywords: complexity, score, difficulty, estimate, sizing, 1-5 scale Solves: How complex is this task? Score task complexity on 1-5 scale, assess implementation difficulty

关键词： complexity, score, difficulty, estimate, sizing, 1-5 scale 解决问题： 这个任务有多复杂？在1-5级范围内为任务复杂度评分，评估实现难度

blocking-thresholds

Keywords: blocking, threshold, gate, stop, escalate, cannot proceed Solves: When should I block progress? >3 critical questions = BLOCK, Missing dependencies = BLOCK

关键词： blocking, threshold, gate, stop, escalate, cannot proceed 解决问题： 何时应该阻止进度？>3个关键问题=阻止，缺失依赖项=阻止

critical-questions

Keywords: critical questions, unanswered, unknowns, clarify Solves: What are critical questions? Count unanswered, block if >3

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

stuck-detection

Keywords: stuck, failed attempts, retry, 3 attempts, escalate Solves: How do I detect when stuck? After 3 failed attempts, escalate

关键词： stuck, failed attempts, retry, 3 attempts, escalate 解决问题： 如何检测是否陷入困境？3次失败尝试后升级

gate-validation

Keywords: validate, gate check, pass, fail, gate status Solves: How do I validate quality gates? Run pre-task gate validation

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

pre-task-gate-check

Keywords: pre-task, before starting, can proceed Solves: How do I check gates before starting? Assess complexity, identify blockers

关键词： pre-task, before starting, can proceed 解决问题： 启动前如何检查关卡？评估复杂度，识别阻塞因素

complexity-breakdown

Keywords: breakdown, decompose, subtasks, split task Solves: How do I break down complex tasks? Split Level 4-5 into Level 1-3 subtasks

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

requirements-completeness

Keywords: requirements, incomplete, acceptance criteria Solves: Are requirements complete enough? Check functional/technical requirements

关键词： requirements, incomplete, acceptance criteria 解决问题： 需求是否足够完整？检查功能/技术需求

escalation-protocol

Keywords: escalate, ask user, need help, human guidance Solves: When and how to escalate? Escalate after 3 failed attempts

关键词： escalate, ask user, need help, human guidance 解决问题： 何时及如何升级？3次失败尝试后升级

llm-as-judge

Keywords: llm as judge, g-eval, aspect scoring, quality validation Solves: How do I use LLM-as-judge? Evaluate relevance, depth, coherence with thresholds

关键词： llm as judge, g-eval, aspect scoring, quality validation 解决问题： 如何使用LLM-as-judge？评估相关性、深度、连贯性是否符合阈值

yagni-gate

Keywords: yagni, over-engineering, justified complexity, scope check, too complex, simplify Solves: Is this complexity justified? Calculate justified_complexity ratio against project tier, BLOCK if > 2.0, surface simpler alternatives

关键词： yagni, over-engineering, justified complexity, scope check, too complex, simplify 解决问题： 这种复杂度是否合理？计算项目层级对应的合理性复杂度比值，>2.0时阻止，提供更简单的替代方案

quality-gates

Original

Translation

Quality Gates

质量关卡

Overview

概述

Auto-Activate Triggers

自动触发条件

Manual Activation

手动触发方式

Core Concepts

核心概念

Complexity Scoring (1-5 Scale)

复杂度评分（1-5级）

Blocking Thresholds

阻塞阈值

References

参考资料

Complexity Scoring

复杂度评分

Blocking Thresholds & Escalation

阻塞阈值与升级

Quality Gate Workflows

质量关卡工作流

Gate Patterns

关卡模式

LLM Quality Validation

LLM质量验证

Quick Reference

快速参考

Gate Decision Flow

关卡决策流程

Gate Check Template

关卡检查模板

Quality Gate: [Task Name]

质量关卡：[任务名称]

Escalation Template

升级模板

Escalation: Task Blocked

升级：任务被阻止

What Was Tried

已尝试的方案

Need Guidance On

需要指导的内容

Integration with Context System

与上下文系统集成

Integration with Evidence System

与验证系统集成

Best Practices Pattern Library

最佳实践模式库

Pattern Confidence Levels

模式信心等级

Common Pitfalls

常见陷阱

Version History

版本历史

Related Skills

相关技能

Key Decisions

关键决策

Capability Details

能力详情

complexity-scoring

complexity-scoring

blocking-thresholds

blocking-thresholds

critical-questions

critical-questions

stuck-detection

stuck-detection

gate-validation

gate-validation

pre-task-gate-check

pre-task-gate-check

complexity-breakdown

complexity-breakdown

requirements-completeness

requirements-completeness

escalation-protocol