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:

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.

Rubrics by Artifact Type

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

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

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:

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

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).