quality-gates

What this skill does

# Quality Gates Skill

**Version:** 1.0.0
**Type:** Quality Assurance & Risk Management
**Auto-activate:** Task planning, complexity assessment, requirement gathering, before task execution

## Overview

This skill teaches agents how to assess task complexity, enforce quality gates, and prevent wasted work on incomplete or poorly-defined tasks. Inspired by production-grade development practices, quality gates ensure agents have sufficient context before proceeding and automatically escalate when stuck or blocked.

**Key Principle:** Stop and clarify before proceeding with incomplete information. Better to ask questions than to waste cycles on the wrong solution.

---

## When to Use This Skill

### 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
- When uncertain about requirements

---

## Core Concepts

### 1. Complexity Scoring (1-5 Scale)

Assess every task on a 1-5 complexity scale:

**Level 1: Trivial**
- Single file change
- Simple variable rename
- Documentation update
- CSS styling tweak
- < 50 lines of code
- < 30 minutes estimated
- No dependencies
- No unknowns

**Level 2: Simple**
- 1-3 file changes
- Basic function implementation
- Simple API endpoint (CRUD)
- Straightforward component
- 50-200 lines of code
- 30 minutes - 2 hours estimated
- 0-1 dependencies
- Minimal unknowns

**Level 3: Moderate**
- 3-10 file changes
- Multiple component coordination
- API with validation and error handling
- State management integration
- Database schema changes
- 200-500 lines of code
- 2-8 hours estimated
- 2-3 dependencies
- Some unknowns that need research

**Level 4: Complex**
- 10-25 file changes
- Cross-cutting concerns
- Authentication/authorization
- Real-time features (WebSockets)
- Payment integration
- Database migrations with data
- 500-1500 lines of code
- 8-24 hours (1-3 days) estimated
- 4-6 dependencies
- Significant unknowns
- Multiple decision points

**Level 5: Very Complex**
- 25+ file changes
- Architectural changes
- New service/microservice
- Complete feature subsystem
- Third-party API integration
- Performance optimization
- 1500+ lines of code
- 24+ hours (3+ days) estimated
- 7+ dependencies
- Many unknowns
- Requires research and prototyping
- High risk of scope creep

### 2. Quality Gate Thresholds

**BLOCKING Conditions** (MUST resolve before proceeding):

1. **Incomplete Requirements** (>3 critical questions)
   - If you have more than 3 unanswered critical questions, STOP
   - Examples of critical questions:
     - "What should happen when X fails?"
     - "What data structure should I use?"
     - "What's the expected behavior for edge case Y?"
     - "Which API should I call?"
     - "What authentication method?"

2. **Missing Dependencies** (blocked by another task)
   - Task depends on incomplete work
   - Required API endpoint doesn't exist
   - Database schema not ready
   - External service not configured

3. **Stuck Detection** (3 attempts at same task)
   - Tried 3 different approaches, all failed
   - Keep encountering the same error
   - Can't find necessary information
   - Solution keeps breaking other things

4. **Evidence Failure** (tests/builds failing)
   - Tests fail after 2 fix attempts
   - Build breaks after changes
   - Type errors persist
   - Integration tests failing

5. **Complexity Overflow** (Level 4-5 tasks without breakdown)
   - Complex task not broken into subtasks
   - No clear implementation plan
   - Too many unknowns
   - Scope unclear

**WARNING Conditions** (Can proceed with caution):

1. **Moderate Complexity** (Level 3)
   - Can proceed but should verify approach first
   - Document assumptions
   - Plan for checkpoints

2. **1-2 Unanswered Questions**
   - Document assumptions
   - Proceed with best guess
   - Note for review later

3. **1-2 Failed Attempts**
   - Try alternative approach
   - Document what didn't work
   - Consider asking for help

### 3. Gate Validation Process

```markdown
## Quality Gate Check

**Task:** [Task description]
**Complexity:** [1-5 scale]
**Dependencies:** [List dependencies]

### Critical Questions (Must answer before proceeding)
1. [Question 1] - ✅ Answered / ❌ Unknown
2. [Question 2] - ✅ Answered / ❌ Unknown
3. [Question 3] - ✅ Answered / ❌ Unknown

**Unanswered Critical Questions:** [Count]

### Dependency Check
- [ ] All required APIs exist
- [ ] Database schema ready
- [ ] Required services running
- [ ] External APIs accessible
- [ ] Authentication configured

**Blocked Dependencies:** [List]

### Attempt History
- Attempt 1: [What was tried, outcome]
- Attempt 2: [What was tried, outcome]
- Attempt 3: [What was tried, outcome]

**Failed Attempts:** [Count]

### Gate Status
- ✅ **PASS** - Can proceed
- ⚠️ **WARNING** - Proceed with caution
- ❌ **BLOCKED** - Must resolve before proceeding

### Blocking Reasons (if blocked)
- [ ] >3 critical questions unanswered
- [ ] Missing dependencies
- [ ] 3+ failed attempts (stuck)
- [ ] Evidence shows failures
- [ ] Complexity too high without plan

### Actions Required
[List actions needed to unblock]
```

---

## Quality Gate Workflows

### Workflow 1: Pre-Task Gate Validation

**When:** Before starting any task (especially Level 3-5)

**Steps:**

1. **Assess Complexity**
   ```
   Read task description
   Count file changes needed
   Estimate lines of code
   Identify dependencies
   Count unknowns
   → Assign complexity score (1-5)
   ```

2. **Identify Critical Questions**
   ```
   What must I know to complete this?
   - Data structures?
   - Expected behaviors?
   - Edge cases?
   - Error handling?
   - API contracts?

   → List all critical questions
   → Count unanswered questions
   ```

3. **Check Dependencies**
   ```
   What does this task depend on?
   - Other tasks?
   - External services?
   - Database changes?
   - Configuration?

   → Verify dependencies ready
   → List blockers
   ```

4. **Gate Decision**
   ```
   if (unansweredQuestions > 3) → BLOCK
   if (missingDependencies > 0) → BLOCK
   if (complexity >= 4 && !hasPlan) → BLOCK
   if (complexity == 3) → WARN
   else → PASS
   ```

5. **Document in Context**
   ```javascript
   context.tasks_pending.push({
     id: 'task-' + Date.now(),
     task: "Task description",
     complexity_score: 3,
     gate_status: 'pass',
     critical_questions: [...],
     dependencies: [...],
     timestamp: new Date().toISOString()
   });
   ```

### Workflow 2: Stuck Detection & Escalation

**When:** After multiple failed attempts at same task

**Steps:**

1. **Track Attempts**
   ```javascript
   // In context, track attempts
   if (!context.attempt_tracking) {
     context.attempt_tracking = {};
   }

   if (!context.attempt_tracking[taskId]) {
     context.attempt_tracking[taskId] = {
       attempts: [],
       first_attempt: new Date().toISOString()
     };
   }

   context.attempt_tracking[taskId].attempts.push({
     timestamp: new Date().toISOString(),
     approach: "Describe what was tried",
     outcome: "Failed because X",
     error_message: "Error details"
   });
   ```

2. **Check Threshold**
   ```javascript
   const attemptCount = context.attempt_tracking[taskId].attempts.length;

   if (attemptCount >= 3) {
     // ESCALATE - stuck
     return {
       status: 'blocked',
       reason: 'stuck_after_3_attempts',
       escalate_to: 'user',
       attempts_history: context.attempt_tracking[taskId].attempts
     };
   }
   ```

3. **Escalation Message**
   ```markdown
   ## 🚨 Escalation: Task Stuck

   **Task:** [Task description]
   **Attempts:** 3
   **Status:** BLOCKED - Need human guidance

   ### What Was Tried
   1. **Attempt 1:** [Approach] → Failed: [Reason]
   2. **Attempt 2:** [A