gmacko-qa-verify

name	gmacko-qa-verify
description	Use when (1) verifying a feature is complete against acceptance criteria, (2) running QA checklist before release, (3) validating PR changes meet requirements. Performs systematic QA verification with documented results.
license	MIT
compatibility	opencode
metadata	{"phase":"qa","tier":"workhorse","permission":"allow"}

Gmacko QA Verification

Systematically verify feature completion against acceptance criteria and produce QA handoff document.

When to Use

• Feature implementation is complete
• PR is ready for QA review
• Before promoting to staging/production
• User requests verification of specific functionality

Prerequisites

• Feature plan exists: docs/ai/handoffs/{feature}-plan.md
• Dev handoff exists: docs/ai/handoffs/{feature}-dev.md
• Code changes are deployed to testable environment

Workflow

digraph qa_verify {
    rankdir=TB;
    node [shape=box];
    
    start [label="Start QA" shape=ellipse];
    gather [label="1. Gather Context"];
    criteria [label="2. Load Acceptance Criteria"];
    functional [label="3. Functional Testing"];
    cross [label="4. Cross-Platform Testing"];
    edge [label="5. Edge Case Testing"];
    security [label="6. Security Spot Check"];
    regression [label="7. Regression Check"];
    document [label="8. Document Results"];
    decision [label="9. Go/No-Go Decision"];
    handoff [label="10. Write QA Handoff"];
    done [label="QA Complete" shape=ellipse];
    
    start -> gather -> criteria -> functional;
    functional -> cross -> edge -> security;
    security -> regression -> document -> decision -> handoff -> done;
}

Execution Steps

Step 1: Gather Context

Collect all relevant information:

# Find related artifacts
FEATURE_ID="[from user or issue number]"
PLAN_DOC="docs/ai/handoffs/${FEATURE_ID}-plan.md"
DEV_DOC="docs/ai/handoffs/${FEATURE_ID}-dev.md"

# Check artifacts exist
[ -f "$PLAN_DOC" ] && echo "Plan found" || echo "WARN: No plan doc"
[ -f "$DEV_DOC" ] && echo "Dev handoff found" || echo "WARN: No dev handoff"

Ask user:

I'm starting QA verification for [feature name].

Please confirm:

1. Which environment should I test? (local/staging/production)
2. Is there a specific PR to review? (#number)
3. Any areas of particular concern?

Step 2: Load Acceptance Criteria

Extract criteria from the feature plan:

## Acceptance Criteria (from plan)

### Functional Requirements
- [ ] AC1: [Description]
- [ ] AC2: [Description]
- [ ] AC3: [Description]

### Non-Functional Requirements
- [ ] Performance: [Target]
- [ ] Accessibility: [Standard]
- [ ] Security: [Requirements]

If no plan exists, ask user for acceptance criteria.

Step 3: Functional Testing

Test each acceptance criterion:

## Functional Test Results

### AC1: [User can create a new project]
**Steps Taken:**
1. Navigated to /projects
2. Clicked "New Project" button
3. Filled form with test data
4. Submitted form

**Expected:** Project created, redirected to project page
**Actual:** [Describe what happened]
**Result:** PASS / FAIL
**Evidence:** [Screenshot URL or description]

### AC2: [Project appears in dashboard]
...

For each criterion:

• Document exact steps taken
• Record expected vs actual behavior
• Capture evidence (describe what you observed)
• Mark PASS/FAIL

Step 4: Cross-Platform Testing

If feature affects multiple platforms:

## Cross-Platform Results

| Platform | Tested | Result | Notes |
|----------|--------|--------|-------|
| Web - Chrome | Yes | PASS | |
| Web - Firefox | Yes | PASS | |
| Web - Safari | Yes | PASS | Minor style issue |
| Web - Mobile | Yes | PASS | |
| iOS Simulator | Yes | PASS | |
| Android Emulator | No | SKIP | Not applicable |

Step 5: Edge Case Testing

Test boundary conditions:

## Edge Cases

### Empty State
- [ ] No data displays appropriate message
- [ ] CTA to create first item visible

### Maximum Limits
- [ ] Form validates max length
- [ ] List handles 100+ items

### Error States
- [ ] Network error shows retry option
- [ ] Invalid input shows validation message
- [ ] Unauthorized access redirects to login

### Concurrent Access
- [ ] Multiple tabs don't conflict
- [ ] Real-time updates work correctly

Step 6: Security Spot Check

Quick security verification:

## Security Check

- [ ] Authentication required where expected
- [ ] User can only see their own data
- [ ] No sensitive data in console/network logs
- [ ] Form inputs properly validated
- [ ] No XSS vulnerabilities (test with `<script>alert(1)</script>`)

Step 7: Regression Check

Verify related features still work:

## Regression Check

### Related Features
- [ ] [Feature A] - Still working
- [ ] [Feature B] - Still working
- [ ] [Feature C] - Still working

### General Health
- [ ] Login/logout works
- [ ] Navigation works
- [ ] No new console errors
- [ ] No new Sentry errors (check dashboard)

Step 8: Document Results

Compile test summary:

## Test Summary

| Category | Passed | Failed | Skipped | Total |
|----------|--------|--------|---------|-------|
| Acceptance Criteria | 5 | 0 | 0 | 5 |
| Cross-Platform | 4 | 0 | 2 | 6 |
| Edge Cases | 8 | 1 | 0 | 9 |
| Security | 5 | 0 | 0 | 5 |
| Regression | 3 | 0 | 0 | 3 |
| **Total** | **25** | **1** | **2** | **28** |

### Issues Found

| ID | Description | Severity | Blocking? |
|----|-------------|----------|-----------|
| QA-1 | Empty state message missing | Medium | No |

Step 9: Go/No-Go Decision

Based on results, make recommendation:

APPROVED - All criteria met, no blocking issues

Recommendation: APPROVED

All acceptance criteria verified. 1 minor issue found (non-blocking).
Feature is ready for release.

APPROVED WITH NOTES - Minor issues, can release

Recommendation: APPROVED WITH NOTES

Acceptance criteria met. Issues found:
- QA-1: Minor UX issue (create follow-up ticket)

Proceed with release, address issues in next sprint.

NOT APPROVED - Blocking issues found

Recommendation: NOT APPROVED

Blocking issues found:
- AC3 not met: Data not persisting correctly
- Security: Unauthorized access possible

Must fix before release. See issues section.

Step 10: Write QA Handoff

Create docs/ai/handoffs/{feature}-qa.md:

# QA Handoff: [Feature Name]

## Summary
- **Feature**: [Name]
- **Issue**: #[number]
- **PR**: #[number]
- **QA Date**: [YYYY-MM-DD]
- **Tester**: AI Assistant
- **Environment**: [staging/local]

## Recommendation
**[APPROVED / APPROVED WITH NOTES / NOT APPROVED]**

[Brief explanation]

## Acceptance Criteria Results

| Criterion | Result | Notes |
|-----------|--------|-------|
| AC1 | PASS | |
| AC2 | PASS | |
| AC3 | PASS | Minor delay observed |

## Test Coverage

| Category | Pass Rate |
|----------|-----------|
| Functional | 100% |
| Cross-Platform | 100% |
| Edge Cases | 89% |
| Security | 100% |
| Regression | 100% |

## Issues Found

### Blocking
None

### Non-Blocking
1. **QA-1**: Empty state message missing
   - Severity: Medium
   - Impact: UX only
   - Recommendation: Create follow-up issue

## Test Evidence

[Links to screenshots, recordings, or descriptions]

## Next Steps
- [ ] Address blocking issues (if any)
- [ ] Create follow-up issues for non-blocking items
- [ ] Proceed to release preparation

---

**Sign-off**: [Tester name]
**Date**: [YYYY-MM-DD]

Automated Checks

Run these commands as part of verification:

# Code quality
pnpm typecheck
pnpm lint

# Build verification
pnpm build

# Check for console errors in browser
# Check Sentry for new errors
# Check PostHog for analytics events

Red Flags

Rationalization	Correction
"It works on my machine"	Test in the specified environment
"Edge cases can wait"	Edge cases reveal real bugs
"Security is someone else's job"	Basic security checks are everyone's job
"No plan doc, I'll guess the criteria"	ASK for criteria before testing
"Minor issues, I'll approve anyway"	Document ALL issues; let stakeholders decide

Integration

• Input: Feature ID, environment, PR number
• References: Feature plan, dev handoff, checklists
• Output: docs/ai/handoffs/{feature}-qa.md
• Next: gmacko-release-prepare (if approved)