/quality-gates

name: quality-gates
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Task complexity scoring (1-5), escalation when stuck, and best-practice checks. Use before complex tasks or after repeated failed attempts."
skills: [scope-appropriate-architecture]
user-invocable: false
disable-model-invocation: false
effort: high
hooks:
  PreToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs skill/quality-baseline-loader"
          once: true
metadata:
  owner-agent: "code-quality-reviewer"
  category: document-asset-creation
  version: "1.3.0"
  author: "OrchestKit"
  complexity: "max"
  tags: "quality, complexity, planning, escalation, blocking, best-practices, patterns, yagni, over-engineering"
allowed-tools: "Read Glob Grep WebFetch WebSearch"

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 |

The table above is the canonical rubric. Score with `max(file_count, LOC, dependency_count, unknowns)`, not an average: one Level 5 axis makes the task Level 5. Run `scripts/assess-complexity.md` or `scripts/analyze-codebase.sh <target>` to measure the inputs.

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

The escalation protocol and gate decision logic are both in "Quick Reference" below. The YAGNI ratio, tier LOC budgets, and simpler-alternative surfacing live in `rules/yagni-gate.md`.

---

References

Load on demand with `Read("references/<file>")`: | File | Content | |------|---------| | `ork-delta.md` | OrchestKit-specific scars and house decisions: line-counting correctness, fail-open policy, gate self-monitoring, non-bypassable categories | | `unified-scoring-framework.md` | Canonical 0-10 dimensions, weights, grade thresholds, improvement prioritization. Also loaded by `ork:assess` and `ork:verify` |

---

Upstream coverage (do not restate)

This skill wraps generic quality-gate practice and keeps only the OrchestKit delta. When one of these topics comes up, go to the source instead of re-teaching it here.

| Topic | Source | |-------|--------| | Complexity 1-5 rubric, per-level examples, assessment formula | "Complexity Scoring" table above, canonical | | BLOCKING vs WARNING conditions, escalation protocol, attempt tracking | "Blocking Thresholds" and "Quick Reference" above, canonical | | YAGNI ratio, project tier LOC budgets, simpler alternatives | `rules/yagni-gate.md` + `ork:scope-appropriate-architecture` | | Score dimensions, weights, grade thresholds | `references/unified-scoring-framework.md` | | LLM-as-judge, G-Eval, aspect scoring, metric APIs | `ork:testing-llm` | | Requirements completeness, acceptance criteria templates | `ork:write-prd` | | Test standards enforced as part of a gate | `ork:architecture-patterns` | | Repo metrics for a gate input (files, LOC, tests, churn) | `scripts/analyze-codebase.sh` in this skill | | LangGraph conditional routing for a gate node | https://langchain-ai.github.io/langgraph/ | | FastAPI error responses for a failed gate | https://fastapi.tiangolo.com/tutorial/handling-errors/ | | Pydantic validators for gate output schemas | https://docs.pydantic.dev/latest/concepts/validators/ | | Retry with exponential backoff, SLO-based alerting on gates | https://sre.google/workbook/alerting-on-slos/ |

---

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:**