improve-website

# Improve a Website

An interactive, resumable journey that turns a live-but-underperforming website into a ranked backlog of
defensible fixes. Across eight phases it diagnoses why visitors don't convert, then fixes usability,
hierarchy, typography, message, speed, memory, and errors — asking you at each decision point and
recording results in `docs/`. Each change is tied to a reason; the big ones ship as tests.

## Core Principle

**Diagnose, fix, prove: evidence from real visitors decides what changes, and every fix ships as a
testable hypothesis.** Order is deliberate — research first, then usability, look, message, speed,
memory, and error-tolerance, because each phase's output feeds the next.

This skill sequences the phases, asks the decision questions, and records what you decide. The
constituent skills carry the method — invoke them rather than improvising their frameworks.

## Journey Map

| Phase | Skill | Question it answers | Artifact |
|---|---|---|---|
| 1 | cro-methodology | Why don't visitors convert, and which fix moves the most money? | Extends docs/METRICS.md, docs/WEBSITE.md, docs/EXPERIMENTS.md — GATE |
| 2 | ux-heuristics | Where do visitors stumble before they weigh the offer? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 3 | refactoring-ui | Does the page look as clear as it reads? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 4 | web-typography | Can visitors comfortably read the copy? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 5 | storybrand-messaging | Does a stranger grasp the offer in five seconds? | Extends docs/POSITIONING.md, docs/EXPERIMENTS.md |
| 6 | high-perf-browser | Does the page arrive before patience runs out? | Extends docs/METRICS.md, docs/WEBSITE.md, docs/EXPERIMENTS.md |
| 7 | made-to-stick | Is the idea memorable enough to survive to the decision? | Extends docs/POSITIONING.md, docs/EXPERIMENTS.md |
| 8 | design-everyday-things | Do the visitors who act ever get stuck? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |

## Operating Rules

1. **Resume first.** Before anything else, read `docs/IMPROVE-WEBSITE-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted.
2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/IMPROVE-WEBSITE-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan.
3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose.
4. **Skill invocation and fallback.** Load the phase's skill and use it: each phase's Invoke line names the skill by slug — use that skill to run the phase. If it is not available, offer: `npx skills add wondelai/skills/<slug> --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in.
5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect.
6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`.
7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names.
8. **Diagnose before redesigning.** No visual or copy change ships before the Phase 1 diagnosis produces evidence for it, and every change lands in EXPERIMENTS.md with a pre-committed metric. A fix with no Phase 1 finding behind it goes back to Phase 1; a bold change with no test attached stays in the backlog until it has one.

## Intake

Ask these before creating the tracker:

1. **What page or flow are we improving, and what is the ONE action it should drive?** (Scopes every
   phase; gates Phase 1 — a page with three CTAs has no goal.)
2. **What is the conversion problem in your words, and what evidence do you have** — analytics,
   bounce rate, drop-off? (Feeds the Phase 1 funnel diagnosis.)
3. **Do you have real visitor input** — exit surveys, reviews, support tickets, recordings — or can
   you get it? (Phase 1's counter-objections must use the customer's own words.)
4. **Roughly how much traffic per week?** (Decides whether A/B tests can reach significance; low
   traffic leans on the qualitative and heuristic phases.)
5. **Which complaint do you hear most** — "looks unprofessional," "nobody understands what we do,"
   "it's slow," "the text is hard to read"? (Routes which fix phase to front-load, per the guide FAQ.)
6. **Do you have existing positioning or brand docs (POSITIONING.md)?** (Phase 5 and 7 build on them.)
7. **Can you paste real assets** — URLs, live copy, CSS, analytics screenshots? (The skills are only
   as good as the evidence you feed them.)

Skip heuristics: skip Phase 4 if body text already meets 16px / ~66ch / 1.5-1.7 line height; skip Phase 6
if Core Web Vitals are already green (but triage a fast LCP fix first if the page barely renders); skip
Phase 5 or 7 if messaging is already validated and clear. Never skip Phase 1 — it aims every