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

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

   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

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

   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

   ## 🚨 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:** [Ap