Quality Gates Skill | Agent Skills

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

Agent Skills: Quality Gates

Install this agent skill to your local

Skill Files