quality-gates

What this skill does

# Quality Gates

**Version:** 1.0.0
**Purpose:** Patterns for approval gates, iteration loops, and quality validation in multi-agent workflows
**Status:** Production Ready

## Overview

Quality gates are checkpoints in workflows where execution pauses for validation before proceeding. They prevent low-quality work from advancing through the pipeline and ensure user expectations are met.

This skill provides battle-tested patterns for:
- **User approval gates** (cost gates, quality gates, final acceptance)
- **Iteration loops** (automated refinement until quality threshold met)
- **Issue severity classification** (CRITICAL, HIGH, MEDIUM, LOW)
- **Multi-reviewer consensus** (unanimous vs majority agreement)
- **Feedback loops** (user reports issues → agent fixes → user validates)
- **Test-driven development loops** (write tests → run → analyze failures → fix → repeat)

Quality gates transform "fire and forget" workflows into **iterative refinement systems** that consistently produce high-quality results.

## Core Patterns

### Pattern 1: User Approval Gates

**When to Ask for Approval:**

Use approval gates for:
- **Cost gates:** Before expensive operations (multi-model review, large-scale refactoring)
- **Quality gates:** Before proceeding to next phase (design validation before implementation)
- **Final validation:** Before completing workflow (user acceptance testing)
- **Irreversible operations:** Before destructive actions (delete files, database migrations)

**How to Present Approval:**

```
Good Approval Prompt:

"You selected 5 AI models for code review:
 - Claude Sonnet (embedded, free)
 - Grok Code Fast (external, $0.002)
 - Gemini 2.5 Flash (external, $0.001)
 - GPT-5 Codex (external, $0.004)
 - DeepSeek Coder (external, $0.001)

 Estimated total cost: $0.008 ($0.005 - $0.010)
 Expected duration: ~5 minutes

 Proceed with multi-model review? (Yes/No/Cancel)"

Why it works:
✓ Clear context (what will happen)
✓ Cost transparency (range, not single number)
✓ Time expectation (5 minutes)
✓ Multiple options (Yes/No/Cancel)
```

**Anti-Pattern: Vague Approval**

```
❌ Wrong:

"This will cost money. Proceed? (Yes/No)"

Why it fails:
✗ No cost details (how much?)
✗ No context (what will happen?)
✗ No alternatives (what if user says no?)
```

**Handling User Responses:**

```
User says YES:
  → Proceed with workflow
  → Track approval in logs
  → Continue to next step

User says NO:
  → Offer alternatives:
    1. Use fewer models (reduce cost)
    2. Use only free embedded Claude
    3. Skip this step entirely
    4. Cancel workflow
  → Ask user to choose alternative
  → Proceed based on choice

User says CANCEL:
  → Gracefully exit workflow
  → Save partial results (if any)
  → Log cancellation reason
  → Clean up temporary files
  → Notify user: "Workflow cancelled. Partial results saved to..."
```

**Approval Bypasses (Advanced):**

For automated workflows, allow approval bypass:

```
Automated Workflow Mode:

If workflow is triggered by CI/CD or scheduled task:
  → Skip user approval gates
  → Use predefined defaults (e.g., max cost $0.10)
  → Log decisions for audit trail
  → Email report to stakeholders after completion

Example:
  if (isAutomatedMode) {
    if (estimatedCost <= maxAutomatedCost) {
      log("Auto-approved: $0.008 <= $0.10 threshold");
      proceed();
    } else {
      log("Auto-rejected: $0.008 > $0.10 threshold");
      notifyStakeholders("Cost exceeds automated threshold");
      abort();
    }
  }
```

---

### Pattern 2: Iteration Loop Patterns

**Max Iteration Limits:**

Always set a **max iteration limit** to prevent infinite loops:

```
Typical Iteration Limits:

Automated quality loops: 10 iterations
  - Designer validation → Developer fixes → Repeat
  - Test failures → Developer fixes → Repeat

User feedback loops: 5 rounds
  - User reports issues → Developer fixes → User validates → Repeat

Code review loops: 3 rounds
  - Reviewer finds issues → Developer fixes → Re-review → Repeat

Multi-model consensus: 1 iteration (no loop)
  - Parallel review → Consolidate → Present
```

**Exit Criteria:**

Define clear **exit criteria** for each loop type:

```
Loop Type: Design Validation

Exit Criteria (checked after each iteration):
  1. Designer assessment = PASS → Exit loop (success)
  2. Iteration count >= 10 → Exit loop (max iterations)
  3. User manually approves → Exit loop (user override)
  4. No changes made by developer → Exit loop (stuck, escalate)

Example:
  for (let i = 1; i <= 10; i++) {
    const review = await designer.validate();

    if (review.assessment === "PASS") {
      log("Design validation passed on iteration " + i);
      break;  // Success exit
    }

    if (i === 10) {
      log("Max iterations reached. Escalating to user validation.");
      break;  // Max iterations exit
    }

    await developer.fix(review.issues);
  }
```

**Progress Tracking:**

Show clear progress to user during iterations:

```
Iteration Loop Progress:

Iteration 1/10: Designer found 5 issues → Developer fixing...
Iteration 2/10: Designer found 3 issues → Developer fixing...
Iteration 3/10: Designer found 1 issue → Developer fixing...
Iteration 4/10: Designer assessment: PASS ✓

Loop completed in 4 iterations.
```

**Iteration History Documentation:**

Track what happened in each iteration:

```
Iteration History (ai-docs/iteration-history.md):

## Iteration 1
Designer Assessment: NEEDS IMPROVEMENT
Issues Found:
  - Button color doesn't match design (#3B82F6 vs #2563EB)
  - Spacing between elements too tight (8px vs 16px)
  - Font size incorrect (14px vs 16px)
Developer Actions:
  - Updated button color to #2563EB
  - Increased spacing to 16px
  - Changed font size to 16px

## Iteration 2
Designer Assessment: NEEDS IMPROVEMENT
Issues Found:
  - Border radius too large (8px vs 4px)
Developer Actions:
  - Reduced border radius to 4px

## Iteration 3
Designer Assessment: PASS ✓
Issues Found: None
Result: Design validation complete
```

---

### Pattern 3: Issue Severity Classification

**Severity Levels:**

Use 4-level severity classification:

```
CRITICAL - Must fix immediately
  - Blocks core functionality
  - Security vulnerabilities (SQL injection, XSS, auth bypass)
  - Data loss risk
  - System crashes
  - Build failures

  Action: STOP workflow, fix immediately, re-validate

HIGH - Should fix soon
  - Major bugs (incorrect behavior)
  - Performance issues (>3s page load, memory leaks)
  - Accessibility violations (keyboard navigation broken)
  - User experience blockers

  Action: Fix in current iteration, proceed after fix

MEDIUM - Should fix
  - Minor bugs (edge cases, visual glitches)
  - Code quality issues (duplication, complexity)
  - Non-blocking performance issues
  - Incomplete error handling

  Action: Fix if time permits, or schedule for next iteration

LOW - Nice to have
  - Code style inconsistencies
  - Minor refactoring opportunities
  - Documentation improvements
  - Polish and optimization

  Action: Log for future improvement, proceed without fixing
```

**Severity-Based Prioritization:**

```
Issue List (sorted by severity):

CRITICAL Issues (must fix all before proceeding):
  1. SQL injection in user search endpoint
  2. Missing authentication check on admin routes
  3. Password stored in plaintext

HIGH Issues (fix before code review):
  4. Memory leak in WebSocket connection
  5. Missing error handling in payment flow
  6. Accessibility: keyboard navigation broken

MEDIUM Issues (fix if time permits):
  7. Code duplication in auth controllers
  8. Inconsistent error messages
  9. Missing JSDoc comments

LOW Issues (defer to future):
  10. Variable naming inconsistency
  11. Redundant type annotations
  12. CSS could use more specificity

Action Plan:
  - Fix CRITICAL (1-3) immediately → Re-run tests
  - Fix HIGH (4-6) before code review
  - Log MEDIUM (7-9) for next iteration
  - Ignore LOW (10-12) for now
```

**Severity Escalation:**

Issues can escalate in severity based on context:

```