heymegabyte/agent-skills / 07-quality-and-verification
quality-and-verification
Unverified5-level verification pyramid: static→unit→Playwright E2E (homepage-first, 6bp)→AI visual→post-deploy. 8-check quality gate. Multi-agent testing (functional/security/a11y/performance). Playwright v1.56+ AI agents (Planner/Generator/Healer, v1.63 current). WCAG 2.2 AA via axe-core v4.13. Percy+Chromatic visual regression. ADA Title II 2027/2028 deadlines.
ui-completeness-sweep.md
View on GitHub---
name: "UI Completeness Sweep"
description: "Playwright + GPT Image 2 vision sweep that finds incomplete UI: disabled buttons, empty states, Coming soon, placeholder images, broken links, unfinished forms, missing error states. Runs BEFORE declaring done. Blocks completion until zero findings."
updated: "2026-04-23"
related: visual-inspection-loop.md (3-round per-page vision), completeness-verification.md (5-pass full-project)
---
# UI Completeness Sweep (***MANDATORY BEFORE DONE***)
> **Model migration note (pass-78, 2026-06-09)**: `GPT-4o` → **GPT Image 2 vision**. Per `platform.openai.com/docs/deprecations`. Sweep protocol unchanged.
## Why This Exists
AI builds 90% of a feature then declares done; the skipped last 10% (empty states, error handling, skeletons, disabled buttons, placeholder text) is what users actually see. This sweep catches it.
## The Sweep (Playwright + GPT Image 2 vision)
### Phase 1: Static Code Scan (fast, catches obvious)
```bash
# Run BEFORE visual sweep — catches what's in the code but not rendered
grep -rn --include="*.ts" --include="*.tsx" --include="*.html" --include="*.js" \
-iE "coming soon|todo|fixme|placeholder|lorem|not implemented|stub|mock data|fake|dummy|sample|example\.com|TBD|WIP|hack|temp|untitled" \
src/ | grep -v node_modules | grep -v ".spec." | grep -v ".test."
```
ANY match = not done. Fix every one.
### Phase 2: Playwright Interactive Sweep
```typescript
// Navigate every route as a real user would
// For EACH page:
// 1. Screenshot full page (all 6 breakpoints)
// 2. Find all buttons — click each one, verify something happens
for (const btn of await page.locator('button, [role="button"], a.btn').all()) {
const text = await btn.textContent();
const disabled = await btn.getAttribute('disabled');
const ariaDisabled = await btn.getAttribute('aria-disabled');
if (disabled || ariaDisabled) findings.push(`Disabled button: "${text}" — needs implementation or removal`);
if (!disabled) {
await btn.click({ timeout: 3000 }).catch(() =>
findings.push(`Button "${text}" — click does nothing or errors`)
);
}
}
// 3. Find all forms — submit with valid AND invalid data
for (const form of await page.locator('form').all()) {
// Submit empty → verify error messages appear
// Submit valid → verify success state
// Check: are all inputs labeled? Do errors clear on correction?
}
// 4. Find all links — verify none are dead
for (const link of await page.locator('a[href]').all()) {
const href = await link.getAttribute('href');
if (href && !href.startsWith('#') && !href.startsWith('javascript')) {
const resp = await page.request.get(href).catch(() => null);
if (!resp || resp.status() >= 400) findings.push(`Dead link: ${href}`);
}
}
// 5. Find all images — verify none are broken or placeholder
for (const img of await page.locator('img').all()) {
const src = await img.getAttribute('src');
const alt = await img.getAttribute('alt');
const natural = await img.evaluate(el => el.naturalWidth);
if (!natural || natural === 0) findings.push(`Broken image: ${src}`);
if (!alt) findings.push(`Missing alt text: ${src}`);
if (src?.includes('placeholder') || src?.includes('via.placeholder'))
findings.push(`Placeholder image: ${src}`);
}
// 6. Check empty states — render pages with no data
// Clear localStorage, delete test data, navigate — what does the user see?
// If blank/broken → needs empty state design
// 7. Check loading states — throttle network, navigate
// await page.route('**/*', route => setTimeout(() => route.continue(), 3000));
// Screenshot during load — is there a skeleton/spinner or just blank?
// 8. Check error states — trigger failures
// Block API responses, submit bad data, revoke auth
// Does the UI handle it gracefully or crash?
```
### Phase 3: GPT Image 2 vision Analysis
For each screenshot, ask GPT Image 2 vision:
> "You are a QA engineer reviewing a deployed SaaS product. Look at this screenshot and identify:
>
> 1. Any UI element that looks unfinished, placeholder, or broken
> 2. Any button/link that appears non-functional (grayed out, no hover state)
> 3. Any section that looks empty or missing content
> 4. Any text that says Coming Soon, TODO, placeholder, sample, example
> 5. Any image that looks like a stock placeholder or is broken
> 6. Any form that appears incomplete (missing labels, no validation)
> 7. Any layout that breaks at this viewport width
> 8. Any element that a user would perceive as unfinished
>
> Rate completeness 0-10. List every finding with exact location. 10 = ship it. Below 8 = not done."
### Phase 4: Fix Loop
```
findings = sweep() // a11y tree + axe-core first (FREE), GPT Image 2 vision detail:low 2bp only for aesthetics
while findings.length > 0 AND round < 3:
for finding in findings:
implement_fix(finding)
deploy()
findings = sweep() // re-sweep: a11y tree first, vision only if aesthetic issues remain
round++
// $1 vision budget cap. Homepage/ATF gets vision priority. a11y tree catches 80% at zero cost.
```
## What Specifically to Catch
- **Disabled buttons** (UI) → implement the handler or remove the button
- **"Coming soon" text** (anywhere) → build the feature or remove the section
- **Empty arrays rendering blank** (lists, tables, feeds) → add empty state with CTA
- **Forms with no validation** (any form) → add Zod validation + error messages
- **Links to `#` or `javascript:void`** (nav, buttons) → wire to real routes
- **Console errors** (any page) → fix every error, zero tolerance
- **Missing loading states** (data-fetching pages) → add skeleton / spinner
- **Missing error boundaries** (every page) → add error UI with retry
- **404 on internal routes** (navigation) → fix routing or remove link
- **Placeholder images** (hero, cards, avatars) → generate real images (Ideogram / Pexels / Pixabay)
- **Truncated text / overflow** (mobile breakpoints) → fix CSS, add `text-overflow`
- **Missing favicon** (browser tab) → generate and add via Ideogram
- **Missing OG image** (social sharing) → generate 1200×630 preview image
## Integration Points
- `completeness-checker` agent runs this sweep
- `visual-qa` agent runs the GPT Image 2 vision analysis
- `deploy-verifier` agent runs post-deploy checks
- The orchestrator MUST run this before declaring any build task complete
- The Stop hook SHOULD verify this ran (check for sweep results in audit log)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |