BMAD-METHOD/bmad-core/tasks/qa-gate.md

qa-gate

Create or update a quality gate decision file for a story based on review findings.

Purpose

Generate a standalone quality gate file that provides a clear pass/fail decision with actionable feedback. This gate serves as an advisory checkpoint for teams to understand quality status.

Prerequisites

• Story has been reviewed (manually or via review-story task)
• Review findings are available
• Understanding of story requirements and implementation

Gate File Location

ALWAYS create file at: docs/qa/gates/{epic}.{story}-{slug}.yml

Slug rules:

• Convert to lowercase
• Replace spaces with hyphens
• Strip punctuation
• Example: "User Auth - Login!" becomes "user-auth-login"

Minimal Required Schema

schema: 1
story: "{epic}.{story}"
gate: PASS|CONCERNS|FAIL|WAIVED
status_reason: "1-2 sentence explanation of gate decision"
reviewer: "Quinn"
updated: "{ISO-8601 timestamp}"
top_issues: []  # Empty array if no issues
waiver: { active: false }  # Only set active: true if WAIVED

Schema with Issues

schema: 1
story: "1.3"
gate: CONCERNS
status_reason: "Missing rate limiting on auth endpoints poses security risk."
reviewer: "Quinn"
updated: "2025-01-12T10:15:00Z"
top_issues:
  - id: "SEC-001"
    severity: high  # ONLY: low|medium|high
    finding: "No rate limiting on login endpoint"
    suggested_action: "Add rate limiting middleware before production"
  - id: "TEST-001"
    severity: medium
    finding: "No integration tests for auth flow"
    suggested_action: "Add integration test coverage"
waiver: { active: false }

Schema when Waived

schema: 1
story: "1.3"
gate: WAIVED
status_reason: "Known issues accepted for MVP release."
reviewer: "Quinn"
updated: "2025-01-12T10:15:00Z"
top_issues:
  - id: "PERF-001"
    severity: low
    finding: "Dashboard loads slowly with 1000+ items"
    suggested_action: "Implement pagination in next sprint"
waiver:
  active: true
  reason: "MVP release - performance optimization deferred"
  approved_by: "Product Owner"

Gate Decision Criteria

PASS

• All acceptance criteria met
• No high-severity issues
• Test coverage meets project standards

CONCERNS

• Non-blocking issues present
• Should be tracked and scheduled
• Can proceed with awareness

FAIL

• Acceptance criteria not met
• High-severity issues present
• Recommend return to InProgress

WAIVED

• Issues explicitly accepted
• Requires approval and reason
• Proceed despite known issues

Severity Scale

FIXED VALUES - NO VARIATIONS:

• low: Minor issues, cosmetic problems
• medium: Should fix soon, not blocking
• high: Critical issues, should block release

Issue ID Prefixes

• SEC-: Security issues
• PERF-: Performance issues
• REL-: Reliability issues
• TEST-: Testing gaps
• MNT-: Maintainability concerns
• ARCH-: Architecture issues
• DOC-: Documentation gaps
• REQ-: Requirements issues

Output Requirements

1. ALWAYS create gate file at: docs/qa/gates/{epic}.{story}-{slug}.yml
2. ALWAYS append this exact format to story's QA Results section:

   Gate: {STATUS} → docs/qa/gates/{epic}.{story}-{slug}.yml
   

3. Keep status_reason to 1-2 sentences maximum
4. Use severity values exactly: low, medium, or high

Example Story Update

After creating gate file, append to story's QA Results section:

## QA Results

### Review Date: 2025-01-12
### Reviewed By: Quinn (Test Architect)

[... existing review content ...]

### Gate Status
Gate: CONCERNS → docs/qa/gates/1.3-user-auth-login.yml

Key Principles

• Keep it minimal and predictable
• Fixed severity scale (low/medium/high)
• Always write to standard path
• Always update story with gate reference
• Clear, actionable findings