Qa Workflow

---
name: qa-workflow
description: QA validation and fix loop workflow — validates implementation completeness then iterates fix cycles until all acceptance criteria pass and quality gates clear
version: 1.1.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit, Bash, Glob, Grep]
agents: [qa, developer, code-reviewer]
category: 'Validation & Quality'
tags: [qa, testing, validation, fix-loop, quality-assurance, sign-off]

verified: true
lastVerifiedAt: 2026-02-22T00:00:00.000Z
best_practices:
  - Be thorough - you are the last line of defense
  - Be specific with file paths and line numbers
  - Fix what QA found, don't add features
error_handling: graceful
streaming: supported
source: builtin
trust_score: 100
provenance_sha: 20cc308c655217c9
---

# QA Workflow Skill

## Overview

Comprehensive quality assurance workflow that validates implementation completeness and correctness, then iterates through fix cycles until approval. You are the last line of defense before shipping.

**Core principle:** You are the last line of defense. If you approve, the feature ships. Be thorough.

## When to Use

**Always:**

- After implementation is marked complete
- Before merging or deploying changes
- When validating acceptance criteria

**Exceptions:**

- Documentation-only changes (may use minimal validation)
- Trivial fixes with skip_validation flag

## Iron Laws

1. **NEVER** approve without verifying every acceptance criterion — you are the last line of defense; partial verification equals no verification.
2. **ALWAYS** document issues with exact file paths and line numbers — vague reports like "the tests fail" are unfixable and waste the fix loop cycle.
3. **NEVER** sign off on implementation with failing tests — all test categories (unit, integration, E2E) must pass before approval, no exceptions.
4. **ALWAYS** run the full test suite for regression check — a feature that breaks existing functionality is not production-ready regardless of new test results.
5. **NEVER** exceed 5 fix loop iterations without escalating to human review — repeated loops signal a root cause that automated fixes cannot resolve.

## Anti-Patterns

| Anti-Pattern                                          | Why It Fails                                                        | Correct Approach                                                                |
| ----------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Approving before checking all acceptance criteria     | Ships bugs disguised as features; breaks the quality contract       | Verify every criterion in the spec before writing the verdict                   |
| Writing vague issue reports ("tests fail", "broken")  | Developer cannot reproduce or fix what is not precisely described   | Include file path, line number, exact error message, and reproduction steps     |
| Signing off with known failing tests                  | Failing tests are documented bugs being shipped to production       | All tests must pass; if tests are wrong, fix them first and document the change |
| Only running new tests, not the full regression suite | New code breaking old functionality is invisible without full suite | Always run full suite with `--coverage`; regressions block approval             |
| Fixing more than QA found to "clean things up"        | Over-fixing introduces new bugs and scope creep into the fix loop   | Apply minimal changes; fix only what QA identified, nothing more                |

Every acceptance criterion must be verified before approval.

## Part 1: QA Review

### Phase 0: Load Context

```bash
# Read the spec (your source of truth for requirements)
cat .claude/context/specs/[task-name]-spec.md

# Read any previous QA reports
cat .claude/context/reports/qa/qa-report.md 2>/dev/null || echo "No previous report"

# See what files were changed
git diff main...HEAD --name-status

# Read QA acceptance criteria from spec
grep -A 100 "## QA Acceptance" spec.md
```

### Phase 1: Verify All Work Completed

```bash
# Check git log for implementation commits
git log --oneline main..HEAD

# Verify expected files were modified
git diff main...HEAD --name-only
```

**STOP if implementation is not complete.** QA runs after implementation.

### Phase 2: Start Test Environment

```bash
# Start services as needed
npm run dev  # or appropriate command

# Verify services are running
curl http://localhost:3000/health 2>/dev/null || echo "Service not responding"
```

Wait for all services to be healthy before proceeding.

### Phase 3: Run Automated Tests

#### Unit Tests

Run all unit tests for affected areas:

```bash
# Run test suite
npm test
# or
pytest
# or
go test ./...
```

**Document results:**

```
UNIT TESTS:
- [area-name]: PASS/FAIL (X/Y tests)
```

#### Integration Tests

Run integration tests if applicable:

```bash
# Run integration test suite
npm run test:integration
```

**Document results:**

```
INTEGRATION TESTS:
- [test-name]: PASS/FAIL
```

#### End-to-End Tests

If E2E tests exist:

```bash
# Run E2E test suite
npm run test:e2e
```

**Document results:**

```
E2E TESTS:
- [flow-name]: PASS/FAIL
```

### Phase 4: Manual Verification

For each acceptance criterion in the spec:

1. **Navigate** to the relevant area
2. **Verify** the criterion is met
3. **Check** for console errors
4. **Test** edge cases
5. **Document** findings

```
MANUAL VERIFICATION:
- [Criterion 1]: PASS/FAIL
  - Evidence: [what you observed]
- [Criterion 2]: PASS/FAIL
  - Evidence: [what you observed]
```

### Phase 5: Code Review

#### Security Review

Check for common vulnerabilities:

```bash
# Look for security issues
grep -r "eval(" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "innerHTML" --include="*.js" --include="*.ts" . 2>/dev/null
grep -r "dangerouslySetInnerHTML" --include="*.tsx" --include="*.jsx" . 2>/dev/null

# Check for hardcoded secrets
grep -rE "(password|secret|api_key|token)\s*=\s*['\"][^'\"]+['\"]" . 2>/dev/null
```

#### Pattern Compliance

Verify code follows established patterns:

```bash
# Compare new code to existing patterns
# Read pattern files, compare structure
```

**Document findings:**

```
CODE REVIEW:
- Security issues: [list or "None"]
- Pattern violations: [list or "None"]
- Code quality: PASS/FAIL
```

### Phase 6: Regression Check

Run full test suite to catch regressions:

```bash
# Run ALL tests, not just new ones
npm test -- --coverage
```

Verify key existing functionality still works.

```
REGRESSION CHECK:
- Full test suite: PASS/FAIL (X/Y tests)
- Existing features verified: [list]
- Regressions found: [list or "None"]
```

### Phase 7: Generate QA Report

```markdown
# QA Validation Report

**Task**: [task-name]
**Date**: [timestamp]

## Summary

| Category            | Status    | Details     |
| ------------------- | --------- | ----------- |
| Unit Tests          | PASS/FAIL | X/Y passing |
| Integration Tests   | PASS/FAIL | X/Y passing |
| E2E Tests           | PASS/FAIL | X/Y passing |
| Manual Verification | PASS/FAIL | [summary]   |
| Security Review     | PASS/FAIL | [summary]   |
| Pattern Compliance  | PASS/FAIL | [summary]   |
| Regression Check    | PASS/FAIL | [summary]   |

## Issues Found

### Critical (Blocks Sign-off)

1. [Issue description] - [File/Location]

### Major (Should Fix)

1. [Issue description] - [File/Location]

### Minor (Nice to Fix)

1. [Issue description] - [File/Location]

## Verdict

**SIGN-OFF**: [APPROVED / REJECTED]

**Reason**: [Explanation]

**Next Steps**:

- [If approved: Ready for merge]
- [If rejected: List of fixes needed]
```

Save report to `.claude/context/reports/qa/qa-report.md`

### Phase 8: Decision

#### If APPROVED

```
=== QA VALIDATION COMPLETE ===

Status: APPROVED

All acceptance criteria verified:
- Unit tests: PASS
- Integration tests: PASS
- Manual verification: PASS
- Security review: PASS
- Regression check: PASS

The implementation is production-ready.
Ready for merge.
```

#### If REJECTED

Create fix request and proceed to Part 2.

---

## Part 2: QA Fix Loop

### Phase 0: Load Fix Request

```bash
# Read the QA report with issues
cat .claude/context/reports/qa/qa-report.md

# Identify issues to fix
grep -A 50 "## Issues Found" .claude/context/reports/qa/qa-report.md
```

Extract from report:

- Exact issues to fix
- File locations
- Required fixes
- Verification criteria

### Phase 1: Parse Fix Requirements

Create a checklist from the QA report:

```
FIXES REQUIRED:
1. [Issue Title]
   - Location: [file:line]
   - Problem: [description]
   - Fix: [what to do]
   - Verify: [how to check]

2. [Issue Title]
   ...
```

You must address EVERY issue.

### Phase 2: Fix Issues One by One

For each issue:

1. **Read** the problem area
2. **Understand** what's wrong
3. **Implement** the fix
4. **Verify** the fix locally

**Follow these rules:**

- Make the MINIMAL change needed
- Don't refactor surrounding code
- Don't add features
- Match existing patterns
- Test after each fix

### Phase 3: Run Tests

After all fixes are applied:

```bash
# Run the full test suite
npm test

# Run specific tests that were failing
[failed test commands from QA report]
```

**All tests must pass before proceeding.**

### Phase 4: Self-Verification

Before requesting re-review, verify each fix:

```
SELF-VERIFICATION:
[ ] Issue 1: [title] - FIXED
    - Verified by: [how you verified]
[ ] Issue 2: [title] - FIXED
    - Verified by: [how you verified]
...

ALL ISSUES ADDRESSED: YES/NO
```

If any issue is not fixed, go back to Phase 2.

### Phase 5: Commit Fixes

```bash
# Add fixed files
git add [fixed-files]

# Commit with descriptive message
git commit -m "fix: Address QA issues

Fixes:
- [Issue 1 title]
- [Issue 2 title]

Verified:
- All tests pass
- Issues verified locally"
```

### Phase 6: Signal for Re-Review

```
=== QA FIXES COMPLETE ===

Issues fixed: [N]

1. [Issue 1] - FIXED
   Commit: [hash]

2. [Issue 2] - FIXED
   Commit: [hash]

All tests passing.
Ready for QA re-validation.
```

---

## QA Loop Behavior

The QA → Fix → QA loop continues until:

1. **All critical issues resolved**
2. **All tests pass**
3. **No regressions**
4. **QA approves**

Maximum iterations: 5

If max iterations reached without approval:

- Escalate to human review
- Document all remaining issues
- Save detailed report

## Severity Guidelines

**CRITICAL** - Blocks sign-off:

- Failing tests
- Security vulnerabilities
- Missing required functionality
- Data corruption risks

**MAJOR** - Should fix:

- Missing edge case handling
- Performance issues
- UX problems
- Pattern violations

**MINOR** - Nice to fix:

- Style inconsistencies
- Documentation gaps
- Minor optimizations

## Verification Checklist

Before approving:

- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] All E2E tests pass (if applicable)
- [ ] Manual verification of acceptance criteria
- [ ] Security review complete
- [ ] Pattern compliance verified
- [ ] No regressions found
- [ ] QA report generated

## Common Mistakes

### Approving Too Quickly

**Why it's wrong:** Shipping bugs to users.

**Do this instead:** Check EVERYTHING in the acceptance criteria.

### Vague Issue Reports

**Why it's wrong:** Developer can't fix what they don't understand.

**Do this instead:** Exact file paths, line numbers, reproducible steps.

### Fixing Too Much

**Why it's wrong:** Introducing new bugs while fixing old ones.

**Do this instead:** Minimal changes. Fix only what QA found.

## Integration with Other Skills

This skill works well with:

- **complexity-assessment**: Determines validation depth
- **tdd**: Use TDD to write tests for fixes
- **debugging**: Use when investigating test failures

## Memory Protocol

**Before starting:**
Read `.claude/context/memory/learnings.md`

**After completing:**

- New pattern -> `.claude/context/memory/learnings.md`
- Issue found -> `.claude/context/memory/issues.md`
- Decision made -> `.claude/context/memory/decisions.md`

> ASSUME INTERRUPTION: If it's not in memory, it didn't happen.