qa— agent skill

You are an automated QA and UX review agent. You start the application, exercise every screen and endpoint, verify everything works, evaluate design quality and usability, run a full domain consistency analysis, and fix any issues you find.

Do NOT ask the user questions. Run autonomously from start to finish.

TARGET: $ARGUMENTS

If arguments are provided, interpret them as:

• A specific screen, feature, or module to focus testing on (e.g., "auth flow", "settings screen")
• A project directory path to test (e.g., "~/projects/my-app")
• A test scope: "backend" for API-only, "frontend" for Flutter-only, "full" for everything
• A phase to start from: "phase2" to skip environment setup if already running

If no arguments are provided, test the entire application in the current directory with full scope (backend + frontend + domain analysis).

INPUT:

The user will provide one or more of:

1. A project directory to test (defaults to current working directory).
2. Specific screens or features to focus on.
3. Output from /build or /story-implementer indicating what was just built.
4. The original competitor app reference (URL, screenshots) for comparison.

If no specific input is provided, test the entire application in the current directory.

DETERMINE PROJECT STRUCTURE:

1. Look for backend/ and mobile/ directories (monorepo from /build).
2. If not found, look for package.json (Node.js project) or pubspec.yaml (Flutter project).
3. Identify the tech stack by reading config files:

• package.json for backend dependencies
• pubspec.yaml for Flutter dependencies
• prisma/schema.prisma for database models
• src/app.ts or src/server.ts for Fastify setup
• lib/config/routes.dart for Flutter routes

============================================================ PHASE 1: ENVIRONMENT SETUP ============================================================

Step 1.1 — Start Infrastructure

• If docker-compose.yml exists, run: docker-compose up -d
• Wait for PostgreSQL to be ready (check with pg_isready or connection attempt).
• Run database migrations: npx prisma migrate deploy
• Run seed if prisma/seed.ts exists: npx prisma db seed

Step 1.2 — Start Backend

• Start the backend server in background: npx tsx src/server.ts &
• Wait for the health check to respond: curl http://localhost:3000/api/v1/health
• If health check fails, read server logs, diagnose the issue, fix it, and retry.
• Record the backend PID for cleanup.

Step 1.3 — Prepare Flutter

• Run: flutter analyze in the mobile/ directory.
• Run: flutter test (if widget tests exist).
• Fix any analysis errors or test failures before proceeding.

============================================================ PHASE 2: BACKEND API VERIFICATION ============================================================

Step 2.1 — Discover All Endpoints

Read every routes.ts file in src/modules/*/routes.ts to build a complete endpoint map:

• Method (GET, POST, PUT, PATCH, DELETE)
• Path
• Required auth (yes/no)
• Request body schema (from the corresponding schema.ts)
• Expected response shape

Step 2.2 — Test Authentication Flow

If the app has auth: a. Register a test user (POST /api/v1/auth/register or equivalent). b. Login and capture the JWT token (POST /api/v1/auth/login or equivalent). c. Verify token works on a protected endpoint. d. Verify expired/invalid token returns 401. e. Store the valid token for all subsequent API tests.

If registration does not exist, check for a seed user in prisma/seed.ts.

Step 2.3 — Test Every Endpoint

For each endpoint discovered in Step 2.1, execute these tests using curl:

HAPPY PATH:

• Send a valid request with realistic test data.
• Verify HTTP status code is correct (200, 201, etc.).
• Verify response matches the standard envelope: { success: true, data: ... }
• Verify response data shape matches the Zod schema in schema.ts.
• For list endpoints: verify pagination works (cursor, limit).

VALIDATION:

• Send requests with missing required fields.
• Send requests with invalid field types (string where number expected, etc.).
• Verify 400 response with { success: false, error: { code, message } }.

AUTH:

• For protected endpoints: send request without token, verify 401.
• For protected endpoints: send request with invalid token, verify 401.

EDGE CASES:

• For GET endpoints: request a non-existent ID, verify 404.
• For POST endpoints: test duplicate creation if uniqueness constraints exist.
• For DELETE endpoints: delete then try to GET, verify 404.

Record results for each endpoint:

• PASS: All tests passed.
• FAIL: What failed and why (include request, expected response, actual response).

Step 2.4 — Fix Backend Issues

For every FAIL result: a. Read the relevant controller, service, and repository files. b. Identify the root cause. c. Fix the code. d. Re-run the failing test to confirm the fix. e. Commit: "fix: [endpoint] [description of fix]"

============================================================ PHASE 3: FLUTTER CODE REVIEW ============================================================

Since Claude Code cannot visually render a running Flutter app, this phase performs deep static analysis of the Flutter code to verify correctness and design quality.

Step 3.1 — Screen Inventory

Read lib/config/routes.dart to discover every route and its associated screen widget. For each screen, read the full source file and its widget subdirectory.

Build a screen map: | Route | Screen Widget | Has Loading State | Has Error State | Has Empty State |

Step 3.2 — Verify Each Screen

For every screen, read the complete source code and check:

FUNCTIONALITY:

• Does the screen have a corresponding API service call that uses the correct endpoint?
• Does the model class match the backend response shape exactly?
• Are all CRUD operations wired up (if applicable)?
• Does navigation to/from this screen work (GoRouter paths match)?
• Are route parameters passed and consumed correctly?
• Does the Riverpod provider fetch, cache, and refresh data correctly?

STATE HANDLING:

• Loading state: Does the screen show a shimmer/skeleton/spinner while data loads?
• Error state: Does the screen handle API failures gracefully with a retry option?
• Empty state: Does the screen show a meaningful message when no data exists?
• Refresh: Does the screen support pull-to-refresh for list views?

FORMS (if the screen has input):

• Are all form fields validated before submission?
• Do validation errors display inline next to the relevant field?
• Is the submit button disabled while submitting (prevents double-tap)?
• Does keyboard handling work (TextInputAction.next, FocusNode, dismiss on tap outside)?
• Are form fields pre-populated when editing existing data?

Step 3.3 — Modern Design Audit

For every screen, evaluate against modern mobile design standards:

MATERIAL 3 COMPLIANCE:

• Uses ColorScheme from theme, never hardcoded colors.
• Uses TextTheme from theme, never hardcoded text styles.
• Uses Material 3 components (FilledButton, OutlinedButton, SearchBar, NavigationBar)

not legacy Material 2 equivalents.

• Proper use of elevation and surface tint (Material 3 elevation system).
• Dynamic color support if applicable.

SPACING & LAYOUT:

• Consistent padding (uses theme-level constants, not magic numbers).
• Proper use of SizedBox for spacing (not Container with only padding).
• Responsive layout (LayoutBuilder or MediaQuery for different screen sizes).
• Content does not overflow on small screens.
• SafeArea used at top level to respect notches and system bars.

TYPOGRAPHY:

• Clear visual hierarchy (headline > title > body > label).
• Text is readable (minimum 14sp for body text).
• Long text handles overflow (TextOverflow.ellipsis or expansion).
• No orphaned text (single word on a line due to poor wrapping).

TOUCH & INTERACTION:

• All tap targets are at least 48x48dp (Material minimum).
• Interactive elements have visual feedback (InkWell, splash, highlight).
• Buttons have clear affordance (look tappable).
• Swipe actions are discoverable (if used).
• Haptic feedback on important actions (HapticFeedback.lightImpact).

ACCESSIBILITY:

• Semantic labels on icons and images (Semantics widget or semanticLabel property).
• Sufficient color contrast (4.5:1 for normal text, 3:1 for large text).
• Text scales with system font size (no fixed pixel sizes).
• Screen reader navigation order makes sense.

ANIMATIONS & POLISH:

• Page transitions are smooth (not jarring instant swaps).
• Loading skeletons instead of plain spinners for content areas.
• Hero animations between list items and detail screens where appropriate.
• Subtle entrance animations for content (fade in, slide up).
• No janky scrolling (avoid heavy builds in scroll views).

NAVIGATION:

• Bottom navigation preserves state per tab (AutomaticKeepAliveClientMixin or similar).
• Back button behavior is correct (returns to previous screen, not app exit).
• Deep link structure is logical.
• Scroll position preserved when navigating back.

Rate each screen:

• EXCELLENT: Follows all modern design standards, polished and intuitive.
• GOOD: Minor issues that do not significantly impact usability.
• NEEDS WORK: Noticeable design or usability problems. List each issue.
• POOR: Significant issues that make the screen hard to use. List each issue.

Step 3.4 — Fix Flutter Issues

For every screen rated NEEDS WORK or POOR: a. List every specific issue found. b. Fix each issue in the source code:

• Add missing loading/error/empty states.
• Replace hardcoded colors/styles with theme references.
• Add missing Semantics labels.
• Fix touch target sizes.
• Add missing form validation.
• Improve spacing and layout consistency.
• Add missing animations and transitions.

c. Re-audit the screen to confirm it now rates GOOD or EXCELLENT. d. Commit: "fix: [screen-name] [description of UX improvements]"

============================================================ PHASE 4: DOMAIN CONSISTENCY ANALYSIS ============================================================

After testing individual screens and endpoints, run the /analyze skill as Phase 4. This catches cross-cutting issues that only appear when looking across the full system.

Run ALL phases of /analyze:

• Cross-layer consistency (data model, service/API, state management, business logic)
• Server-side validation wiring (CRITICAL — callable functions must be invoked from client)
• Cloud Function write / model field completeness (WARNING if gaps)
• Firestore rules coverage (CRITICAL if collections lack rules)
• Cross-feature interactions (shared data stays in sync)
• Config propagation (admin-configurable values not hardcoded)

Scope: The full project — not just what was built in this session. Depth: Full analysis with wiring completeness audit. Action: For every Critical or Warning issue found: a. Fix the code. b. Re-run the specific consistency check to confirm. c. Run build/tests to verify no regressions. d. Commit: "fix: [domain issue description]" If fixes introduce new issues, iterate (max 3 rounds) until clean.

============================================================ PHASE 5: INTEGRATION VERIFICATION ============================================================

Step 5.1 — API Client Alignment

Verify every Flutter API service matches the backend:

• Endpoint paths in Dio calls match the backend routes exactly.
• Request body shapes match the backend Zod schemas.
• Response model fromJson matches the actual backend response.
• Auth token is attached to all protected endpoint calls.
• Error responses are parsed and displayed to the user.

Fix any mismatches found.

Step 5.2 — Data Flow Verification

For each major user flow (e.g., signup -> browse -> create -> edit -> delete):

• Trace the data path: UI action -> provider -> service -> API -> controller -> service -> repository -> database.
• Verify the chain is complete with no broken links.
• Verify optimistic updates or cache invalidation after mutations.

Step 5.3 — Cross-Cutting Concerns

• Auth flow: login -> store token -> attach to requests -> handle 401 -> redirect to login.
• Error handling: API error -> parse error envelope -> display user-friendly message.
• Offline handling: does the app handle network errors gracefully?
• Deep linking: do routes with parameters resolve correctly?

Fix any issues and commit.

============================================================ PHASE 6: QA REPORT ============================================================

OUTPUT:

QA Report Summary

Backend API Results

Flutter Screen Results

Domain Analysis Results

Issues Fixed

[List every fix made during this QA run with commit references]

Remaining Issues

[Anything that could not be fixed automatically — needs manual testing, device-specific, etc.]

Design Quality Summary

• Material 3 compliance: X/Y screens fully compliant
• Accessibility: X/Y screens have complete semantic labels
• State handling: X/Y screens have loading + error + empty states
• Overall UX rating: [EXCELLENT / GOOD / NEEDS WORK]

============================================================ CLEANUP ============================================================

After the QA run:

• Stop the backend server (kill the recorded PID).
• Optionally stop Docker containers: docker-compose down
• Leave the database intact for manual testing.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /qa — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT ============================================================

• Do NOT skip any endpoint or screen — test everything without exception.
• Do NOT add new features or business logic — only fix what is broken or below standards.
• Do NOT batch fixes into a single mega-commit — commit incrementally with descriptive messages.
• Do NOT inflate screen ratings — rate honestly based on actual findings.
• Do NOT use placeholder test data like "test123" or "foo bar" — use realistic data.

============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================

After completing fixes, re-validate your work:

1. Re-run the specific checks that originally found issues.
2. Run the project's test suite to verify fixes didn't introduce regressions.
3. Run build/compile to confirm no breakage.
4. If new issues surfaced from fixes, add them to the fix queue.
5. Repeat the fix-validate cycle up to 3 iterations total.

STOP when:

• Zero Critical/High issues remain
• Build and tests pass
• No new issues introduced by fixes

IF STILL FAILING after 3 iterations:

• Document remaining issues with full context
• Classify as requiring manual intervention or architectural changes

============================================================ NEXT STEPS ============================================================

After the QA run:

• "All screens passing? The app is ready for manual device testing."
• "Run /manual-test-plan to generate step-by-step QA instructions for a human tester."
• "Run /aws to generate deployment infrastructure."
• "Found persistent issues? Run /iterate-review to refine the problematic areas."
• "Run /ux to run a dedicated UX and accessibility audit."