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)