Verify

Stage 6V: Visual & Functional Verification

Verify the RUNNING application against every screen specification and acceptance criterion in the PRD by navigating the app in a browser. Lead a multi-agent verification project using Claude Code Agent Teams.

Read the detailed guide at ${CLAUDE_SKILL_ROOT}/references/verification-detailed-guide.md for full teammate prompts, failure patterns, and report templates.

Read the scenario generation guide at ${CLAUDE_SKILL_ROOT}/references/feature-scenario-generation.md for the algorithm to build the Feature Scenario Matrix.

Prerequisites

1. Verify ./plancasting/_launch/readiness-report.md exists and shows READY. If NOT READY or file missing, STOP -- run Stage 6H first.
2. Create output directories:

   mkdir -p ./plancasting/_audits/visual-verification
   mkdir -p ./screenshots/automated
   mkdir -p ./screenshots/criteria
   mkdir -p ./screenshots/vision
   mkdir -p ./screenshots/visual-verification/baseline
   mkdir -p ./e2e/verification
   

3. Verify Playwright browsers are installed:

   bunx playwright install --with-deps chromium
   

Scope Modes

• full (default) -- All screens in plancasting/prd/08-screen-specifications.md. ~30-60 min.
• critical -- P0/P1 features only. ~15-30 min.
• diff -- Only screens related to files changed since last verification. ~10-20 min. Note: last-verified-commit.txt is created at the END of a 6V run, so diff mode only works on the second or subsequent run. If the file does not exist, automatically falls back to full. Warning: diff mode requires a previous 6V report to diff against — do NOT use for the first 6V run.

How to specify scope: Append MODE: full, MODE: critical, or MODE: diff on a new line after pasting the prompt, or as a separate follow-up message. Default is full.

Important: This stage uses the FULL generation mode (all priorities) of the Feature Scenario Matrix. Do not use critical or diff scope unless explicitly requested by the user.

Input

• Running Application: Dev server (use the dev command from plancasting/tech-stack.md)
• Scenario Generation Guide: ${CLAUDE_SKILL_ROOT}/references/feature-scenario-generation.md
• PRD: ./plancasting/prd/ -- ALL files, especially 02-feature-map-and-prioritization.md, 04-epics-and-user-stories.md, 06-user-flows.md, 07-information-architecture.md, 08-screen-specifications.md
• Tech Stack: ./plancasting/tech-stack.md
• Project Rules: ./CLAUDE.md
• E2E Config: ./playwright.config.ts, ./e2e/helpers/, ./e2e/constants.ts

Check ./plancasting/tech-stack.md for the Session Language setting. Generate all reports in that language. Code and file names remain in English.

Stack Adaptation

The examples use Playwright + Next.js + Convex. Adapt to your plancasting/tech-stack.md: test directory, test runner, dev server command, data fetching patterns. Replace npm run with your project's package manager per CLAUDE.md.

Phase 1: Lead Analysis & Planning

Complete BEFORE spawning teammates:

1. Read project context: ./CLAUDE.md, ./plancasting/tech-stack.md, ${CLAUDE_SKILL_ROOT}/references/feature-scenario-generation.md, ./playwright.config.ts, ./e2e/constants.ts, ./e2e/helpers/

2. Generate the Feature Scenario Matrix following the algorithm in the scenario generation guide:

   • Read ALL PRD sources and extract structured data
   • Read codebase sources (route constants, page files, middleware, auth helpers, schema, layouts)
   • Build the Feature Dependency Graph
   • Generate ALL scenario types: FS-NNN (Feature), AS-NNN (Auth Context), ES-NNN (Entity State), RS-NNN (Role Permission), NS-NNN (Negative)
   • Apply scope filter (full/critical/diff)
   • Cross-reference for coverage gaps -- every screen and route should appear in at least one scenario
   • Save to ./plancasting/_audits/visual-verification/feature-scenario-matrix.md and gap-fill matrix to ./plancasting/_audits/visual-verification/verification-matrix.md

3. Start the application:

   • Kill any existing process on the dev port: lsof -ti:3000 | xargs kill 2>/dev/null || true (Adapt port to your framework's default: Next.js: 3000, Vite/SvelteKit: 5173, Remix: 3000, Astro: 4321)
   • Run the dev server. If BaaS dev server fails non-interactively, set the BaaS URL env var in .env.local and run only the frontend dev server.
   • Wait up to 60 seconds. If the server fails to start, ABORT.

4. Unauthenticated route verification (BEFORE logging in):

   • Identify all public routes from middleware and PRD
   • Open a fresh browser context (no cookies/localStorage/session)
   • Navigate to EVERY public route -- verify HTTP 200 with correct content
   • Test protected routes without auth -- verify redirect to /login
   • Flag ANY public route that incorrectly redirects to login as CRITICAL

5. Verify test users exist: Attempt login with credentials from ./e2e/constants.ts. If login fails, try seed endpoint, auth provider CLI, or UI signup. If all fail, ABORT.

6. Build Navigation Inventory: Read route constants, shared layout components, middleware. Compile a Navigation Checklist appended to the verification matrix.

7. Plan teammate assignments: Assign separate test user accounts to each teammate to prevent state conflicts.

Phase 2: Spawn Verification Teammates

Spawn 4 teammates. Teammates 1, 2, and 4 run in parallel. Teammate 3 runs AFTER Teammate 1 completes.

Teammate 1: "automated-page-verifier"

Systematic page-by-page verification. Tasks: unauthenticated route checks (first), navigation/load verification, component presence, state verification, link integrity crawl, sub-navigation completeness, accessibility quick check, generate Playwright test files.

Teammate 2: "acceptance-criteria-verifier"

Execute Feature Scenarios and acceptance criteria. Tasks: parse and execute Given/When/Then criteria, generate Playwright tests, cross-feature flow verification, dead route detection, auth redirect verification.

Teammate 3: "visual-ai-reviewer" (after Teammate 1)

AI Vision review of screenshots at 3 breakpoints (1440px, 768px, 375px). Tasks: collect/take screenshots, visual spec compliance review (layout, component, content, responsive, design consistency), dark mode review.

Teammate 4: "responsive-and-interaction-verifier"

Interactive behavior and keyboard navigation. Tasks: form/modal/dropdown/tab testing, systematic button action verification, keyboard navigation, responsive functional testing at mobile breakpoints, cross-browser quick check (Chromium, Firefox, WebKit).

Phase 3: Coordination

• If Teammate 1 finds pages that don't load (HTTP 500, blank), flag as CRITICAL
• Aggregate findings across teammates
• If auth fails for ALL test users, ABORT

Phase 4: Verification Report

1. Typecheck generated test files: bun run typecheck
2. Run generated Playwright tests: bunx playwright test e2e/verification/ --grep "@verification" --retries=2
3. Generate report at ./plancasting/_audits/visual-verification/report.md -- include all result sections (scenario results, page-level results, unauthenticated access, acceptance criteria, visual compliance, navigation/link integrity, button actions, sub-navigation, responsive/interaction, gate decision, failure categorization for 6R routing)
4. Commit generated test files if any
5. Save commit hash: git rev-parse HEAD > ./plancasting/_audits/visual-verification/last-verified-commit.txt

Gate Decision (Dual System)

The gate uses TWO systems -- the final gate is the WORSE of the two:

Percentage-based system:

• PASS: >90% acceptance criteria pass, all pages load
• CONDITIONAL PASS: 80-90% criteria pass
• FAIL: <80% criteria pass

Fixability-based category system (uses 6V- prefix to distinguish from 5B):

• 6V-A (auto-fixable): broken links, dead code, incorrect imports -- 6R fixes automatically
• 6V-B (semi-auto): stub components, missing loading states -- 6R fixes with effort. Fixable by: adding component logic + local state, wiring existing hooks to components, adding inline handlers. NOT fixable (escalate to C) if it requires: restructuring state management, creating new hooks, changing API contracts, or modifying database schema.
• 6V-C (human judgment): architectural issues, design decisions -- 6R cannot fix

Dual-system decision matrix:

Percentage	Categories Present	Final Gate	Next Stage
PASS (>90%)	None (zero actionable issues)	PASS	-> 6P/6P-R
PASS (>90%)	A/B only	CONDITIONAL PASS	-> 6R -> 6P/6P-R
PASS (>90%)	C only	PASS	-> 6P/6P-R (document C for human)
PASS (>90%)	Mixed A/B + C	CONDITIONAL PASS	-> 6R -> 6P/6P-R (document remaining C)
CONDITIONAL (80-90%)	A/B present	CONDITIONAL PASS	-> 6R -> 6P/6P-R
CONDITIONAL (80-90%)	C only	CONDITIONAL PASS	-> 6P/6P-R (document C for human)
FAIL (<80%)	Any	FAIL	Manual fix + re-run 6V

Flaky Scenario Handling

A flaky scenario is a test that fails on the first run but passes on a subsequent re-run without code changes, typically caused by timing issues or external service latency. Retest a failing scenario once. If it passes on retest: mark as "FLAKY -- cause TBD" in the Issues table. In 6V, flaky scenarios are informational (do not count toward gate failure). In 7V (production), flaky scenarios count as FAIL.

Next Steps

• PASS: skip 6R -> proceed to Stage 6P or 6P-R (Visual Polish or Redesign) -> Deploy -> 7V -> 7D
• CONDITIONAL PASS with 6V-A/B issues: proceed to Stage 6R (Runtime Remediation)
• CONDITIONAL PASS with ONLY 6V-C issues: skip 6R -> proceed to Stage 6P or 6P-R
• FAIL: fix critical issues manually, then re-run Stage 6V

Phase 5: Shutdown

1. Request shutdown for all teammates
2. Verify all files saved and committed
3. Leave the dev server running for 6R or 6P/6P-R

Critical Rules

1. ALWAYS start the dev server and verify accessibility before spawning teammates. ABORT if it fails within 60 seconds.
2. NEVER skip the AI vision review (Teammate 3).
3. NEVER mark a page as PASS if it has console ERRORS. Console WARNINGS from third-party libraries do not constitute FAIL.
4. ALWAYS test with seeded data.
5. ALWAYS take screenshots on failure.
6. ALWAYS map findings to PRD identifiers (SC-NNN, US-NNN, FEAT-NNN).
7. ALWAYS generate Playwright test files even when using direct browser interaction.
8. This stage FINDS issues -- it does NOT fix them. Fixes happen in Stage 6R.
9. NEVER let one teammate's actions corrupt state for another.
10. For eventually-consistent backends, use expect.poll() or retry assertions (up to 10s timeout).
11. ALWAYS verify test user seeding BEFORE spawning teammates.
12. ALWAYS crawl links from shared layouts (sidebar, header, footer, mobile nav).
13. ALWAYS test navigation at BOTH desktop and mobile viewports.
14. ALWAYS click buttons and verify their action -- not just DOM presence.
15. ALWAYS test auth middleware redirects for ALL public routes.
16. ALWAYS test public routes from a FRESH unauthenticated browser context BEFORE logging in.

Output Specification

Artifact	Path
Feature Scenario Matrix	./plancasting/_audits/visual-verification/feature-scenario-matrix.md
Verification Matrix (gap-fill)	./plancasting/_audits/visual-verification/verification-matrix.md
Verification Report	./plancasting/_audits/visual-verification/report.md
Last Verified Commit	./plancasting/_audits/visual-verification/last-verified-commit.txt
Baseline Screenshots	./screenshots/visual-verification/baseline/
Playwright Test Files	e2e/verification/*.spec.ts
Screenshots	./screenshots/automated/, ./screenshots/criteria/, ./screenshots/vision/