quality-gates

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)
2. If you have more than 3 unanswered critical questions, STOP
3. Examples of critical questions:
4. "What should happen when X fails?"
5. "What data structure should I use?"
6. "What's the expected behavior for edge case Y?"
7. "Which API should I call?"
8. "What authentication method?"

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

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

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

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

WARNING Conditions (Can proceed with caution):

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

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

1. 1-2 Failed Attempts
2. Try alternative approach
3. Document what didn't work
4. 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) ``

1. 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 ```

1. Check Dependencies

``` What does this task depend on?

• Other tasks?
• External services?
• Database changes?
• Configuration?

→ Verify dependencies ready → List blockers ```

1. Gate Decision

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

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

1. 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 }; } ```

1. 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: [Ap