---
title: "Quality Gates"
description: "Use when assessing task complexity, before starting complex tasks, when stuck after multiple attempts, or reviewing code against best practices. Provides quality-gates scoring (1-5), escalation workflows, and pattern library management."
canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/quality-gates"
---

# Quality Gates

Use when assessing task complexity, before starting complex tasks, when stuck after multiple attempts, or reviewing code against best practices. Provides quality-gates scoring (1-5), escalation workflows, and pattern library management.

<span className="badge badge-gray">Reference</span> <span className="badge badge-red">max</span>

> **Auto-activated** — this skill loads automatically when Claude detects matching context.

<ContextualSkillSidebar slug="quality-gates" />

> **Quality Gates** Use when assessing task complexity, before starting complex tasks, when stuck after multiple attempts, or reviewing code against best practices. Provides quality-gates scoring (1-5), escalation workflows, and pattern library management.


# 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 | &lt; 50 | &lt; 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 &lt;target&gt;` 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("$\{CLAUDE_PLUGIN_ROOT\}/skills/quality-gates/references/&lt;file&gt;")`:
| 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

```markdown
## 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

```markdown
## 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

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

## 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' };
}
```

---

## 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
- `ork:testing-llm` - LLM-as-judge patterns for quality validation (DeepEval, RAGAS)
- `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:** Gate check only: is the requirement set complete enough to start? Authoring the requirements themselves belongs to `ork:write-prd` (see Upstream coverage)

### 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:** Gate thresholds only: what score must a judge return to pass? Building and running the judge belongs to `ork:testing-llm` (see Upstream coverage)

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

---

## Rules (3)

### Track success and failure patterns in a library to prevent repeating architectural mistakes — HIGH


## Best Practices Pattern Library

Track and aggregate success/failure patterns across projects to prevent repeating mistakes.

**Incorrect — no pattern tracking:**
```python
# Same team, third project using offset pagination
# Each time it fails at scale, each time nobody remembers
@router.get("/items")
def list_items(page: int = 1, limit: int = 20):
    offset = (page - 1) * limit
    return db.query(Item).offset(offset).limit(limit).all()
    # Timeout on tables with 1M+ rows — again
```

**Correct — pattern library with outcome tracking:**
```python
# Pattern library entry (stored in knowledge graph)
pattern = {
    "category": "pagination",
    "pattern": "cursor-based pagination",
    "outcome": "success",
    "projects": ["project-a", "project-b", "project-c"],
    "confidence": "strong",  # 3+ projects, 100% success
    "note": "Scales well for large datasets"
}

# Anti-pattern entry
anti_pattern = {
    "category": "pagination",
    "pattern": "offset pagination",
    "outcome": "failure",
    "projects": ["project-a", "project-d"],
    "confidence": "strong_anti",  # 2+ projects, all failed
    "note": "Caused timeouts on tables with 1M+ rows",
    "lesson": "Use cursor-based for datasets > 100K rows"
}
```

**Confidence scoring:**

| Level | Meaning | Criteria |
|-------|---------|----------|
| Strong success | Always recommend | 3+ projects, 100% success rate |
| Moderate success | Recommend with caveats | 1-2 projects or some failures |
| Mixed results | Context-dependent | Both successes and failures |
| Anti-pattern | Actively warn against | Only failures |
| Strong anti-pattern | Block with explanation | 3+ projects, all failed |

**Memory integration:**
```bash
# Store a successful pattern
mcp__memory__create_entities(
    entities=[{
      name: "cursor-pagination-success",
      entityType: "best_practice",
      observations: ["Cursor-based pagination works well for large datasets (3 projects)"]
    }]
)

# Query patterns before making architecture decisions
mcp__memory__search_nodes(query="pagination patterns outcomes")
```

**Key rules:**
- Track every significant architectural decision outcome (success or failure)
- Include project name and context so patterns are discoverable
- Proactively query pattern library before repeating known decisions
- Update confidence levels as more project data accumulates


### Run proactive anti-pattern detection to catch known bad patterns in new projects — HIGH


## Best Practices Review Checklist

Use stored patterns to proactively detect anti-patterns and guide reviews.

**Incorrect — reviewing without historical context:**
```python
# Code review misses known anti-pattern because reviewer
# doesn't know the team failed with this approach before
@router.get("/users")
def list_users(page: int = 1):
    # Reviewer approves offset pagination — team failed with
    # this exact pattern on 2 previous projects
    return db.query(User).offset((page-1)*20).limit(20).all()
```

**Correct — proactive pattern-based review:**
```python
# Before review, query pattern library for relevant categories
# patterns = search_patterns(categories=["pagination", "auth", "orm"])

# Review checklist generated from pattern library:
# WARNING: offset pagination — failed in project-a, project-d
#   Lesson: Use cursor-based for datasets > 100K rows
#   Recommendation: Switch to cursor-based pagination

# Approved alternative:
@router.get("/users")
def list_users(cursor: str | None = None, limit: int = 20):
    query = db.query(User).order_by(User.id)
    if cursor:
        query = query.filter(User.id > decode_cursor(cursor))
    results = query.limit(limit + 1).all()
    next_cursor = encode_cursor(results[-1].id) if len(results) > limit else None
    return {"items": results[:limit], "next_cursor": next_cursor}
```

**Category-based review workflow:**

| Step | Action | Source |
|------|--------|--------|
| 1 | Identify categories in PR (auth, DB, API) | Code diff analysis |
| 2 | Query pattern library for those categories | Knowledge graph search |
| 3 | Flag any matching anti-patterns | Automated warning |
| 4 | Suggest proven alternatives from success patterns | Pattern library |
| 5 | Log review outcome for future reference | Memory update |

**Display format for pattern warnings:**
```
PAGINATION
  [strong_success] Cursor-based pagination (3 projects, always worked)
  [strong_anti] Offset pagination (failed in 2 projects)
    Lesson: Use cursor-based for large datasets

AUTHENTICATION
  [strong_success] JWT + httpOnly refresh tokens (4 projects)
  [mixed] Session-based auth (1 success, 1 failure)
    Note: Scaling issues in high-traffic scenarios
```

**Key rules:**
- Query pattern library at the start of every code review
- Flag all matching anti-patterns with their failure history and lessons
- Suggest proven alternatives from the success pattern list
- Update pattern library after review with new outcomes


### Apply the YAGNI gate to prevent over-engineering patterns that never get used — HIGH


## YAGNI Gate

Pre-implementation check that prevents over-engineering by validating complexity against project scope.

**Incorrect — skipping straight to implementation:**
```
Task: "Add user authentication"
→ Immediately builds OAuth2.1 + PKCE + SSO + MFA + custom JWT rotation
→ 2000 LOC for a take-home assignment
```

**Correct — YAGNI gate catches this:**
```
Task: "Add user authentication"
→ YAGNI Gate: Project tier = Interview (detected from README)
→ Scope-appropriate auth = session cookies or hardcoded key
→ Justified complexity ratio = 2000 / 200 = 10.0 → BLOCK
→ Suggestion: "Use session cookies. Add a comment noting what you'd change for production."
```

## YAGNI Gate Questions

Before applying any architecture pattern, answer ALL four:

| # | Question | If "No" |
|---|----------|---------|
| 1 | Does this pattern serve a **current** requirement? | Remove it. "Might need later" is not current. |
| 2 | Could 80% of the value be delivered with 20% of complexity? | Use the simpler version. |
| 3 | Is this the simplest thing that could possibly work? | Simplify until it is. |
| 4 | Is the cost of adding this later significantly higher than now? | If low cost to add later, defer. |

**Pass rule:** Must answer YES to question 1 AND at least one of questions 2-4 must justify current inclusion.

## Justified Complexity Ratio

```
justified_complexity = actual_complexity / scope_appropriate_complexity
```

Where `scope_appropriate_complexity` comes from the project tier (see `scope-appropriate-architecture` skill):

| Tier | Scope-Appropriate LOC | Typical Patterns |
|------|----------------------|------------------|
| Interview/Hackathon | 200-800 | Flat files, inline SQL, no abstractions |
| MVP | 1,000-5,000 | MVC monolith, managed auth, simple ORM |
| Growth/Production | 5,000-30,000 | Layered, repository where needed, DI |
| Enterprise | 30,000+ | Hexagonal, CQRS if justified, full DI |

### Thresholds

| Ratio | Status | Action |
|-------|--------|--------|
| > 2.0 | **BLOCK** | Over-engineered. Must simplify before proceeding. Surface simpler alternatives. |
| 1.5 - 2.0 | **WARN** | Likely over-engineered. Present simpler alternative. Proceed only if user confirms. |
| 1.0 - 1.5 | **OK** | Proportionate complexity. |
| &lt; 1.0 | **OK** | Simpler than expected. Fine. |

### Evaluation Method

Estimate actual complexity by counting planned patterns:

| Pattern | Complexity Cost (LOC) |
|---------|-----------------------|
| Repository per entity | +150-300 |
| Dependency injection framework | +100-200 |
| Domain exceptions hierarchy | +50-100 |
| Generic base repository | +100-200 |
| Unit of Work | +150-250 |
| Event sourcing | +500-2000 |
| CQRS | +300-800 |
| Custom auth (JWT + refresh) | +200-400 |
| Message queue integration | +200-500 |

Sum planned pattern costs. Divide by tier's scope-appropriate LOC ceiling. Apply thresholds.

## Devil's Advocate: Simpler Alternatives

When YAGNI gate triggers WARN or BLOCK, **surface alternatives before implementation** (not buried in references):

```markdown
## YAGNI Gate: Over-Engineering Warning

**Planned approach:** Repository pattern + DI + domain exceptions (est. ~800 LOC)
**Project tier:** MVP (scope-appropriate: ~2,000 LOC)
**Ratio:** 800 / 2000 = 0.4 → OK

But if tier were Interview:
**Ratio:** 800 / 400 = 2.0 → BLOCK

### Simpler Alternative
- Direct ORM calls in route handlers (~150 LOC)
- Inline validation (~50 LOC)
- HTTP exceptions directly (~30 LOC)
- Total: ~230 LOC — delivers same functionality
```

## Integration with Gate Flow

Insert as Step 0 in the quality gate decision flow, **before** complexity assessment:

```
Step 0: YAGNI Check
  → Read project tier (from scope-appropriate-architecture or auto-detect)
  → For each planned pattern: run 4 YAGNI questions
  → Calculate justified_complexity ratio
  → If ratio > 2.0: BLOCK with simpler alternatives
  → If ratio 1.5-2.0: WARN with simpler alternatives

Step 1: Assess complexity (1-5)
Step 2: Count critical questions
Step 3: Check dependencies
Step 4: Check attempt count
Step 5: Final gate decision
```

## Key Rules

- YAGNI gate runs BEFORE implementation planning, not after
- Security patterns are exempt — never simplify auth validation, input sanitization, or SQL parameterization
- The gate evaluates architecture patterns, not business logic complexity
- When blocked, the agent MUST present the simpler alternative to the user
- User can override with explicit confirmation ("I know this is a take-home but I want to demonstrate hexagonal architecture")



---

## References (2)

### Ork Delta

# OrchestKit delta: quality gates

What this skill knows that no vendor doc will tell you. The gate rubric itself
(complexity 1-5, blocking thresholds, the escalation template) lives in `SKILL.md`;
scoring lives in `references/unified-scoring-framework.md`. Everything below is a scar
or a house decision that survived the thinning of the restated tutorials.

Bare filenames in the `Why:` lines (for example `gate-patterns.md`) name files retired
by that thinning. They are provenance, not load pointers, and no longer exist on disk.

## Count files and lines with `awk 'END\{print NR\}'`, never `xargs wc -l | tail -1`

Why: PR #2973 (commit `740dd9c02`) found this skill's own `scripts/analyze-codebase.sh`
and `scripts/assess-complexity.md` shipping the `xargs wc -l | tail -1` recipe. xargs
batches long file lists and wc emits one total per batch, so `tail -1` silently keeps
only the last: a 6k-file tree undercounted by 83%, which drags every downstream
complexity score with it. `grep -c` is not a substitute, it exits 1 on empty input and
aborts `set -euo pipefail` scripts.
Upstream: `src/shared/rules/shell-count-correctness.md`

## Fail open on a quality gate by default, fail closed only for security and money

Why: house threshold ladder, docs 0.6, code generation 0.7, test generation 0.7,
security analysis 0.8, payment and finance 0.9, with max retries 1 / 2 / 2 / 3 / 3.
A stalled workflow costs more than one mediocre paragraph, but a rubber-stamped
security review costs more than a stall, so the fail mode flips with the stake, not
with the score. Distilled from the retired llm-quality-validation.md; no traced
incident.
Upstream: `ork:testing-llm` for the DeepEval and RAGAS metric APIs behind these scores

## Treat a gate's own pass rate as the alarm, not just the work it blocks

Why: house rule, a pass rate under 70% or a bypass rate over 5% means the gate is
miscalibrated or is being routed around, and the first fix is the gate, not the work.
An average retry count above 2 means the gate is not returning actionable feedback.
Distilled from the retired gate-patterns.md and quality-gate-checklist.md; no traced
incident.
Upstream: https://sre.google/workbook/alerting-on-slos/

## Never bypass a gate for security, compliance, or data integrity

Why: house decision. The three sanctioned bypass lanes (explicit human override with a
written justification, emergency mode on a CRITICAL task, an explicitly experimental
feature) all stay narrower than these three categories, because a bypassed security
gate emits no signal that anything was skipped. Distilled from the retired
gate-patterns.md; no traced incident.
Upstream: `ork:security-patterns`

## Score with the unified framework, do not invent a second scale here

Why: `references/unified-scoring-framework.md` is loaded by `ork:assess` and
`ork:verify` through `CLAUDE_PLUGIN_ROOT`, so any local rubric in this skill forks the
grade those two report for the same change. The retired gate references each carried
their own 0.60 / 0.75 / 0.85 threshold table, none of them reconciled with the shared
0-10 dimension weights.
Upstream: `references/unified-scoring-framework.md` in this skill, canonical for
`ork:assess` and `ork:verify`

## Do not ship fill-in gate templates as standalone files

Why: the retired complexity-assessment.md closed by routing the agent to a
`breakdown-template.md` under `.claude/skills/scripts/`, a path that has never existed
anywhere in this repo, and it restated the same 7-criterion rubric already carried by
`scripts/assess-complexity.md` and `SKILL.md`. Standalone templates drift from the gate
flow they claim to implement and dead-end into siblings nobody wrote.
Upstream: `src/skills/CONTRIBUTING-SKILLS.md`

## Do not cite metrics from a codebase this repo does not contain

Why: the retired orchestkit-quality-gates.md presented "203 analyses, 84.7%
first-attempt pass rate, 3.4% escalation" as measured OrchestKit production data, sourced
from a `quality_gate_node.py` under `backend/app/workflows/nodes/`. Asking git for either
path across all refs returns nothing: neither has ever been tracked in this repository, so
the numbers were unfalsifiable and the threshold tuning they justified rested on nothing.
Upstream: `src/shared/rules/verification-gate.md`


### Unified Scoring Framework

# Unified Scoring Framework

Canonical scoring reference shared by `assess`, `verify`, and any skill that produces quality scores. Single source of truth — other skills reference this file instead of defining their own.

## Base Dimensions (7)

| Dimension | Base Weight | What It Measures |
|-----------|-------------|------------------|
| Correctness | 0.15 | Functional accuracy, edge cases, error handling |
| Maintainability | 0.15 | Readability, complexity, naming, single responsibility |
| Performance | 0.12 | Algorithm efficiency, caching, async, latency |
| Security | 0.20 | OWASP Top 10, input validation, secrets, CVEs |
| Scalability | 0.10 | Horizontal scaling, statelessness, load patterns |
| Testability | 0.13 | Coverage, assertion quality, test isolation |
| Compliance | 0.15 | API contracts, UI contracts, schema validation |

**Base Total: 1.00**

## Extended Dimensions

Skills may add dimensions beyond the base 7. When adding:

1. Define the new dimension with its weight
2. Scale all weights so total = 1.00
3. Define scope rules for when the dimension is skipped
4. When skipped, redistribute weight proportionally: `adjusted_weight = base_weight / (1.0 - skipped_weight)`

### Simplicity Dimension (used by `brainstorm`, `assess`)

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| Simplicity | 0.10 | Net complexity change — does this simplify or add to the system? |

**Scoring guide:**

| Score | Criteria |
|-------|----------|
| 9-10 | Removes code/concepts while improving or maintaining the result |
| 7-8 | Neutral complexity — replaces existing with equivalent simplicity |
| 5-6 | Adds moderate complexity proportional to value delivered |
| 3-4 | Adds significant complexity for marginal gain |
| 0-2 | Adds ugly complexity, new abstractions, new concepts for little benefit |

**Scope rule:** Active when evaluating design alternatives, architecture decisions, or refactoring approaches. Skip when reviewing existing code that isn't being compared against alternatives.

> Inspired by [autoresearch](https://github.com/karpathy/autoresearch): "A small improvement that adds ugly complexity is not worth it. Removing something and getting equal or better results is a great outcome."

### Visual Dimension (used by `verify`)

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| Visual | 0.10 | Layout correctness, a11y, content completeness, responsiveness |

When Visual is active, base dimensions scale down by `1.0 / 1.10` factor. When skipped (API-only), base weights stay at 1.00.

### Compliance Scope Rules

| Scope | Compliance Covers |
|-------|-------------------|
| Backend-only | API compliance (contracts, schema validation, versioning) |
| Frontend-only | UI compliance (design system, a11y, responsive) |
| Full-stack | API + UI compliance (split evenly) |

## Composite Score

```
composite = sum(dimension_score * adjusted_weight for each dimension)
```

Each dimension scored **0-10** with decimal precision. Composite is also 0-10.

## Grade Thresholds

| Score | Grade | Verdict | Action |
|-------|-------|---------|--------|
| 9.0-10.0 | A+ | EXCELLENT | Ship it |
| 8.0-8.9 | A | GOOD | Ready for merge |
| 7.0-7.9 | B | GOOD | Minor improvements optional |
| 6.0-6.9 | C | ADEQUATE | Consider improvements |
| 5.0-5.9 | D | NEEDS WORK | Improvements recommended |
| 0.0-4.9 | F | CRITICAL | Do not merge |

## Per-Dimension Scoring Criteria

### Score Levels (all dimensions)

| Range | Level | Description |
|-------|-------|-------------|
| 9-10 | Excellent | Exemplary, reference quality |
| 7-8 | Good | Ready for merge, minor suggestions |
| 5-6 | Adequate | Functional but needs improvement |
| 3-4 | Poor | Significant issues, blocks merge |
| 1-2 | Critical | Fundamental problems |
| 0 | Broken | Does not function |

### Scoring Rules

**Incorrect** (no evidence):
```
Security: "looks fine" → 8/10
Performance: "fast enough" → 7/10
```

**Correct** (evidence-based):
```
Security: "11/11 injection tests pass, 0 CVEs" → 9/10
Performance: "p99 latency 142ms (budget: 300ms), 0 N+1" → 8.5/10
```

## Improvement Prioritization

### Effort Scale (1-5)

| Points | Effort | Description |
|--------|--------|-------------|
| 1 | Trivial | &lt; 15 minutes, single file change |
| 2 | Low | 15-60 minutes, few files |
| 3 | Medium | 1-4 hours, moderate scope |
| 4 | High | 4-8 hours, significant refactoring |
| 5 | Major | 1+ days, architectural change |

### Impact Scale (1-5)

| Points | Impact | Description |
|--------|--------|-------------|
| 1 | Minimal | Cosmetic, no functional change |
| 2 | Low | Minor improvement, limited scope |
| 3 | Medium | Noticeable quality improvement |
| 4 | High | Significant quality or security gain |
| 5 | Critical | Blocks shipping or fixes major vulnerability |

### Priority Formula

```
priority = impact / effort
```

Higher ratio = do first. **Quick Wins**: Effort &lt;= 2 AND Impact &gt;= 4 — always highlight at top.

## Blocking Rules

| Condition | Threshold | Action |
|-----------|-----------|--------|
| Composite below minimum | &lt; 6.0 (configurable) | BLOCK |
| Security below minimum | &lt; 7.0 (configurable) | BLOCK |
| Any critical dimension | &lt; 3.0 | BLOCK |
| Coverage below minimum | &lt; 70% (configurable) | WARN |

Override via `.claude/policies/verification-policy.json`.