Retrofit

retrofit — diagnose before redesigning

Stage: Entry point — before any pipeline phase, for sites ultraweb did not build - Reads: existing codebase, running site, taste - Writes: design/RETROFIT.md, design/screenshots/retrofit/*, qa/visual/round-1/VERDICT.md, reconstructed design/BRIEF.md + DIRECTION.md

Standard

A diagnosis a studio would charge for: every gap carries evidence (a screenshot path or a file:line grep hit), a score against the taste rubric, the ONE ultraweb skill that fixes it, and a phase. Scores come from looking at rendered pages — never from reading code alone. Retrofit is a mutating audit and says so up front: it writes the design record into the repo (design/RETROFIT.md, screenshots, a reconstructed BRIEF.md + DIRECTION.md) and touches app code only where required to boot the site — each boot fix named in RETROFIT.md. All treatment happens afterward, through ultraweb:iterate, one approved phase at a time.

Process

1. Qualify the patient. First: if design/DIRECTION.md already exists, STOP — this is an ultraweb site, and retrofit against it would overwrite real recorded decisions with reconstructed guesses. A complete record is ultraweb:iterate's case; a partial one is the root skill's §Resuming ladder. Then read package.json and the tree. Next.js App Router → proceed. Pages Router, CRA, or another framework → say so and stop; retrofit audits, it doesn't port. Offer a fresh ultraweb build as the alternative.
2. Inventory. Routes (every app/**/page.tsx), components, styling entry (@theme in app/globals.css vs tailwind.config.js — the config file marks Tailwind v3), and deps of record: next major, framer-motion vs motion, zod major, middleware.ts (pre-Next-16 signal) vs proxy.ts. Collect any written direction statement too (style guide, brand page, README §design) — step 6 needs it.
3. Static anti-slop sweep — grep the banned list before rendering anything:
   • lorem, href="#", Feature 1, placeholder.com
   • from-purple-|from-violet-|to-blue- and headline bg-clip-text gradient text
   • ✨|🚀|🎉 and emoji-as-icons in TSX
   • counts of rounded-xl and shadow-lg — near-universal usage = depth without hierarchy
   • Elevate|Unlock the power|Seamlessly|Empower|Welcome to Every hit is a pre-scored gap with file:line evidence.
4. Boot it. npm install, npm run dev. Won't start → hand the verbatim error to stack-doctor and apply the minimal fix that gets pixels on screen. No other code changes during the audit.
5. Screenshot everything. pixel-qa drives Playwright MCP, outputDir: design/screenshots/retrofit/: viewport frames per route at 375/768/1440, light + dark when a toggle exists, plus 1440 sectionals. No full-page captures — the judge refuses frames >2500px. Console errors are recorded as gaps.
6. Score. mkdir -p qa, then dispatch design-judge as round 1, pointed at design/screenshots/retrofit/ as the round directory (frames + sectionals), the project and plugin roots. No design/DIRECTION.md exists — step 1 refused the site if it did — so hand it the step-2 direction statement as the stand-in and tell it to score against the taste constitution and the award-canon invariants alone. It scores its own fixed six axes, writes the full review to qa/visual/round-1/VERDICT.md, returns ≤700 tokens: scores, ranked defects, verdict, plus round-1's antislop/responsive lines — fold every violation into the gap table. Compute the mean and the worst axis yourself from that table — the judge returns neither.
7. Map every gap to one skill (table below). A gap without a named fixing skill isn't finished — "improve the design" ships nothing.
8. Phase the plan into design/RETROFIT.md: A quick wins → B system fixes → C direction change (only when triggered).
9. Bootstrap the artifacts iterate needs. Reverse-engineer design/BRIEF.md from the evident site (audience, purpose, pages, backend surface) — including the machine-read fields every consumer expects: Deployment mode: production (an existing live site is production; never guess demo) and, when the site serves a named market, §Compliance facts reconstructed from the Impressum and shop surface (flag each entry counsel-needed — reconstructed facts are assumptions, not knowledge). Write design/DIRECTION.md as the TARGET direction — the existing aesthetic sharpened, or, when Phase C triggers, a fresh pick via ultraweb:direction.
10. Hand off. Present RETROFIT.md. Each approved phase executes via ultraweb:iterate with this file as the change request. Phase C is the burn-it-down case: get explicit user confirmation of scope before starting it.

Scoring rubric

design-judge's six fixed axes, 1–10 per page — Motion folded into Craft (its contract has no Motion axis):

Report the WORST axis alongside the mean — a 7.0 average hiding a 2/10 distinctiveness IS a distinctiveness problem. Triggers: any axis ≤4 → its system fix goes to Phase B. Distinctiveness ≤4, or no identifiable direction at all → Phase C candidate.

Gap → skill map (canonical examples)

RETROFIT.md format

# Retrofit — <site> (<date>)
Verdict: <one sentence>. Mean <n>/10, worst axis: <axis> <n>/10.

## Scorecard
| axis | score | evidence (screenshot / file:line) |

## Gaps
| # | gap | evidence | severity P0–P3 | skill | phase |

## Plan
- Phase A — quick wins (hours, local, reversible): #3, #7, #9…
- Phase B — system fixes (globals.css tokens + foundation skills): #1, #2… [B-0 stack migration first if flagged]
- Phase C — direction change (only if triggered; confirm scope with the user): …
Execute each phase via ultraweb:iterate, pointing it at this file and the phase id.

Anti-patterns

• Fixing while auditing — the only permitted edit is whatever boots the dev server
• Scores produced without screenshots — code reading is inventory, not judgment
• "Improve visual hierarchy" with no skill, no evidence, no phase — that's a shrug, not a gap
• Every gap mapped to "rebuild it" — Phase C is the exception; most sites need B
• Reporting only the mean score — the worst axis is the headline
• Treating tailwind.config.js as cosmetic — it blocks the entire token strategy; migration is B-0
• Skipping the artifact bootstrap — iterate refuses sites without design/BRIEF.md and DIRECTION.md

Worked example — Ledger & Lane, auditing the firm's inherited site

Moved to references/example.md — read only when this build's case is genuinely ambiguous; the sections above are the decision material.

Composes with

Moved to references/composes.md — the handoff map; load it when orchestrating this skill against its neighbors.