quality-gates

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.

---

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

Manual Activation

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

---

Core Concepts

Complexity Scoring (1-5 Scale)

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

Load: Read("${CLAUDE_SKILL_DIR}/references/complexity-scoring.md") for detailed examples and assessment formulas.

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

Load: Read("${CLAUDE_SKILL_DIR}/references/blocking-thresholds.md") for escalation protocols and decision logic.

---

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

File	Content
complexity-scoring.md	Detailed Level 1-5 characteristics, quick assessment formula, checklist
blocking-thresholds.md	BLOCKING vs WARNING conditions, escalation protocol, gate decision logic, attempt tracking
workflows.md	Pre-task gate validation, stuck detection, complexity breakdown (Level 4-5), requirements completeness
gate-patterns.md	Gate validation process templates, context system integration, common pitfalls
llm-quality-validation.md	LLM-as-judge patterns, quality aspects, fail-open/closed strategies, graceful degradation, triple-consumer artifacts

---

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

Gate Check Template

## 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 Template

## 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]

---

Integration with Context System

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

Integration with Evidence System

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

---

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

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

---

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

---

---

Related Skills

• ork:scope-appropriate-architecture - Project tier detection that feeds YAGNI gate
• ork:architecture-patterns - Enforce testing standards as part of quality gates
• llm-evaluation - LLM-as-judge patterns for quality validation
• ork:golden-dataset - Validate datasets meet quality thresholds

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

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

blocking-thresholds

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

critical-questions

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

stuck-detection

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

gate-validation

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

pre-task-gate-check

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

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

requirements-completeness

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

escalation-protocol

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

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

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