---
name: quality-gate
description: Quality gate for SDD artifacts (specs, ADRs, tasks, code). Use when generating or updating specs, ADRs, task decomposition, or code implementation to validate quality before delivering to the user. Do not use for linting, code formatting, human code review, or validation of intermediate artifacts marked as draft/WIP.
---

# Quality Gate — SDD Artifact Validation

## Principle

SDD artifacts propagate quality downstream: a vague spec generates ambiguous tasks that generate incorrect code. Evaluating quality at the point of creation is cheaper than fixing it later.

## When to Use

Use this skill **after generating an artifact and before presenting it to the user**:

| Agent | Artifact | Activate when |
|-------|----------|---------------|
| `devsquad.specify` | spec.md | Spec generated or updated |
| `devsquad.plan` | ADRs, plan.md | ADR created or plan finalized |
| `devsquad.decompose` | tasks.md, work items | Task decomposition completed |
| `devsquad.implement` | Code | Medium or high impact task implemented |
| `devsquad.extend` | `*.agent.md` | Custom agent created or modified |

**Do not use for**: low impact tasks (typo, log, formatting), intermediate artifacts that will be reviewed manually, or when the user explicitly asks to skip validation.

## General Flow

```
Generate artifact → Evaluate against rubric → Identify failures → Fix → Re-evaluate (if needed) → Deliver
```

Maximum of **2 correction iterations**. If after 2 attempts there are still failures, deliver the artifact with documented failures for human decision.

## Evaluation Levels

Evaluation depth scales with the artifact's risk. Use the classification from the `complexity-analysis` skill when available, or infer from context.

| Level | When | What to evaluate |
|-------|------|------------------|
| **Quick** | Low impact, established pattern | Only critical criteria (immediate FAIL) |
| **Standard** | Medium impact, most artifacts | Complete rubric for the artifact type |
| **Deep** | High impact, high risk, first time | Complete rubric + cross-verification with related artifacts |

---

## Rubrics by Artifact Type

Each artifact type has a dedicated rubric. Read **only** the rubric for the artifact being evaluated:

| Artifact | Rubric |
|----------|--------|
| spec.md (feature) | Read `references/rubrica-spec.md` |
| spec.md (migration) | Read `references/rubrica-migration-spec.md` |
| ADR | Read `references/rubrica-adr.md` |
| tasks.md / work items | Read `references/rubrica-tasks.md` |
| Code (implementation) | Read `references/rubrica-code.md` |

To determine spec type: if the spec is under `docs/migrations/`, use the migration rubric. If under `docs/features/`, use the feature rubric.

---

## Output Format

After evaluation, present the result in a compact form. Adapt to the evaluation level.

### If ALL critical criteria pass

```
Evaluation: [artifact type]
Result: OK (N/N critical criteria pass)
Alerts: [list quality criteria that failed, if any]
```

Proceed with delivery to the user.

### If any critical criterion FAILS

```
Evaluation: [artifact type]
Result: FAILURES FOUND

Critical:
- [ID]: [dimension] — [what is wrong] → [how to fix]

Quality:
- [ID]: [dimension] — [observation]

Fixing automatically...
```

Fix the critical issues, re-evaluate, and only then deliver.

### If failures persist after 2 iterations

```
Evaluation: [artifact type]
Result: PERSISTENT FAILURES (after 2 correction attempts)

Unresolved failures:
- [ID]: [dimension] — [description] — Reason: [why it could not be resolved]

Action needed: Human decision on how to proceed.
```

Deliver the artifact with documented failures.

---

## Convergence and Limits

| Parameter | Value | Justification |
|-----------|-------|---------------|
| Max correction iterations | 2 | Avoid infinite loop. If 2 attempts don't resolve it, the problem requires human intervention. |
| Timeout per evaluation | Proportional to artifact | Spec: evaluate all dimensions. Task with 50 items: 30% sampling. |
| Sampling for tasks | If > 20 tasks, evaluate 100% of critical criteria + 30% sample for quality | Balance between coverage and context cost. |

## When NOT to Evaluate

- User explicitly asked to skip: "generate directly", "no validation"
- Artifact is a declared draft: "draft", "WIP", "exploratory"
- Re-evaluation of an artifact that already passed (unless it has been modified)

## Recording Failure-Driven Amendments

When `quality-gate` evaluates a spec, ADR, or agent file that was amended in response to a failure (rather than to add new scope), require the Spec Evolution Log Trigger column to use one of the three failure category names from `debugging-recovery/references/failure-taxonomy.md`:

| Trigger value | Use when |
|---|---|
| `failure (spec)` | Amendment closes a case the spec did not previously cover, disambiguates a clause, or tightens Non-Scope |
| `failure (validation)` | Amendment adds a conformance case, test, or rubric criterion the validation surface missed |
| `failure (agent)` | Amendment fixes a misaligned agent body, composition declaration, tool config, or handoff |

For non-failure triggers (new work, drift detected proactively, external constraint), use `new work`, `drift`, or `external constraint`. For a trigger that does not fit either set, use `other (<short reason>)` as a transitional escape hatch; this raises a quality alert prompting the maintainers to consider whether a new category is warranted.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "AI-generated code is probably fine" | AI code needs more scrutiny, not less. It is confident and plausible, even when wrong. |
| "The tests pass, so it is good" | Tests are necessary but not sufficient. They do not catch architecture problems, security issues, or readability concerns. |
| "It works, that is good enough" | Working code that is unreadable, insecure, or architecturally wrong creates debt that compounds. |
| "This is a simple change, skip validation" | Simple changes break builds. Validation is fast for simple artifacts anyway. |
| "We will clean it up later" | Later never comes. The quality gate is the enforcement point. Use it. |

## Red Flags

- Artifacts approved without evidence of actual evaluation
- Review that only checks if tests pass (ignoring other dimensions)
- Accepting "I will fix it later" without a concrete work item
- Security-sensitive changes without security-focused evaluation
- No regression tests accompanying bug fix implementations

## Anti-patterns

- Do not invent problems to seem useful. If the artifact is good, say "OK" and move on.
- Do not evaluate style or formatting that is already covered by markdownlint or existing linters.
- Do not block delivery for quality criteria (only critical criteria block).
- Do not re-evaluate infinitely: maximum 2 iterations, then escalate to human.
- Do not evaluate artifacts outside the scope of the current agent (e.g., devsquad.specify does not evaluate tasks).