superpowers-sage-verifying

name	superpowers-sage:verifying
description	Verify implemented work meets acceptance criteria — run tests, check PHPCS, validate Blade output, lando phpunit, lando phpcs, lando yarn test, Playwright tests, accessibility check, post-implementation verification, done criteria validation, checklist review, verification phase
user-invocable	true
argument-hint	[section name or plan path]

Verifying — Visual Comparison with Design Reference

Compare implemented sections against design reference using visual analysis.

Inputs

$ARGUMENTS

Procedure

0) Playwright gate

Before any verification work, ToolSearch for mcp__plugin_playwright_playwright__browser_take_screenshot.

If NOT found:

⛔ Cannot verify without Playwright MCP.

Install: claude mcp add playwright -- npx -y @anthropic/playwright-mcp
Restart session after installing. Stop.

Do NOT proceed to reference source detection.

1) Determine reference source

Priority order:

0. Live design MCP (Priority 0 — preferred when MCP is configured):
   • Figma: get_design_context + get_metadata
   • Paper: get_computed_styles + get_node_info
   • Pencil: batch_get(resolveVariables: true) + batch_get(readDepth: 4)
   • Stitch: get_screen Use when the design MCP is active in the session — live reference is always more accurate than cached assets.
1. Spec file: docs/plans/<active-plan>/assets/section-*-spec.md — read “Verification Inputs” block to get url, selector, and ref path
2. Plan assets: docs/plans/<active-plan>/assets/section-*.png — reference image for comparison
3. Last resort: ask user to provide screenshot or describe expected appearance

1b) Node geometry (multi-column / offset components)

When the reference source is a design MCP and the component contains a grid with 2+ columns, offset positioning, or nested containers, fetch node geometry before capturing the implementation screenshot:

• Figma: call get_metadata — returns x, y, width, height for each direct child
• Paper: call get_node_info — returns width + computed sizes for selected node
• Pencil: call batch_get(readDepth: 4) — returns layout children with dimensions
• Stitch: column count and widths visible in the get_screen response

Use these values to confirm column widths (e.g., a 60/40 split) before comparing screenshots. Skipping this step on multi-column layouts is a common source of false MATCH verdicts.

2) Capture implementation

1. Read Verification Inputs block from the spec file — extract url, selector, ref
2. Read canonical viewport width from plan.md frontmatter (viewport-width field, default 1440 if absent)
3. Set viewport: mcp__plugin_playwright_playwright__browser_resize to {viewport-width} x 900 before navigating
4. Navigate Playwright to url: mcp__plugin_playwright_playwright__browser_navigate
5. Take screenshot scoped to selector: mcp__plugin_playwright_playwright__browser_take_screenshot
6. If selector fails (element not found), take full-page screenshot and note the difference

3) Compare visually

Read both reference and implementation images. Compare on these axes:

Axis	Check
Layout	Grid structure, column count, alignment, flex direction
Content	Headlines match? Body text match? All items present?
Colors	Background, text, accent colors match?
Typography	Font size, weight, family approximately correct?
Spacing	Padding, margins, gaps reasonable?
Icons	Correct icon set? Right icon names?
Images	Placeholder or actual? Right aspect ratio?
Responsive	Does the layout adapt appropriately?

3b) Style spot-check (paper sources only)

This step is additive — it runs only when assets/section-{name}.styles.json exists (i.e., the source was paper). For all other sources, skip silently and proceed to step 4.

1. Read docs/plans/<active-plan>/assets/section-{name}.styles.json
2. For each key property (typography, colors, spacing, border-radius), find the implemented value:
   • Tailwind class (p-6, text-lg, bg-slate-900) — resolve to its real value via the project's Tailwind config (tailwind.config.js or @theme block in resources/css/app.css). For example, p-6 → padding: 1.5rem → 24px.
   • Arbitrary value (p-[23px]) — capture the literal between brackets.
3. Compare design value vs implemented value. Produce a per-section report block:

### Style Spot-Check
✓ padding:    design=24px, impl=p-6 (24px)
✗ font-size:  design=18px, impl=text-base (16px)  — DRIFT
✓ color:      design=#0F172A, impl=bg-slate-900 (#0F172A)
⚠ gap:        design=32px, impl=gap-[31px] — arbitrary value, near-match

4. Non-fatal: drift here does NOT block verification. The drift items are surfaced as warnings inside the final report (step 4) under a ### Style Drift subsection. The user decides whether to adjust.

4) Report findings

Output a structured report:

## Verification: {Section Name}

**Status:** MATCH | DRIFT | MISSING

### Comparison
| Axis | Status | Notes |
|---|---|---|
| Layout | {pass/drift} | {details} |
| Content | {pass/drift} | {details} |
| Colors | {pass/drift} | {details} |
| Typography | {pass/drift} | {details} |
| Spacing | {pass/drift} | {details} |

### Issues Found
- {specific issue with fix suggestion}

### Style Drift
{omit this section if source was not paper, or no drift found.
 Otherwise list the ✗ and ⚠ lines from the spot-check.}

### Recommendation
{proceed / fix before continuing}

5) Act on findings

• MATCH: Mark component as verified, proceed
• DRIFT: List specific fixes needed, implement if in /building flow
• MISSING: Elements from design not implemented — flag for implementation

Key Principles

• Read images from disk — always use Read tool for plan assets
• Be specific — "the grid should be 3 columns, got 2" not "layout is wrong"
• Compare content verbatim — headlines and body text must match exactly
• Use base skill: verification-before-completion for completion gate