improve-app

# Improve an App

The app already ships and works — users, screens, a real flow — but the experience feels rough where it
should feel effortless. Across nine phases this journey fixes what users feel, in evidence order: re-anchor
on the job, remove friction, polish the look and the moments, sharpen the words, persuade honestly, and end
with a review brutal enough to cut. It is interactive (the agent asks before deciding) and resumable (state
lives in `docs/`). Code-level causes route out to the code journeys — this pass fixes the product experience.

## Core Principle

**Fix what users feel, in evidence order: re-anchor on the job the app is hired for, remove friction before
polish, sharpen the words, persuade honestly, and end with a review brutal enough to cut.** A prettier
screen on a confusing flow loses users at the same rate — the order of the phases is the whole game.

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

## Journey Map

| Phase | Skill | Question it answers | Artifact |
|---|---|---|---|
| 1 | jobs-to-be-done | What job is the app hired for, and where does it underdeliver? | Extends docs/CUSTOMER.md — GATE |
| 2 | ux-heuristics | Where does the interface make users stop and think? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 3 | design-everyday-things | Where do users act wrong because the design misled them? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 4 | refactoring-ui | Does the app look as clear as it works? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 5 | microinteractions | Does every action feel alive, or dead? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 6 | made-to-stick | Do the in-app words land, or read as jargon? | Extends docs/POSITIONING.md, docs/EXPERIMENTS.md |
| 7 | influence-psychology | Do the paywall and upgrade moments persuade honestly? | Extends docs/POSITIONING.md, docs/EXPERIMENTS.md |
| 8 | high-perf-browser | Does the app feel fast where users touch it? | Extends docs/DESIGN.md, docs/EXPERIMENTS.md |
| 9 | steve-jobs-design-review | Is the whole experience insanely great, or just better? | Extends docs/PRODUCT.md, docs/DESIGN.md, docs/EXPERIMENTS.md |

## Operating Rules

1. **Resume first.** Before anything else, read `docs/IMPROVE-APP-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-APP-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. **Evidence before redesign; persuasion stays honest.** No UI or copy change ships without an audit or evidence row from Phases 1-3 behind it — a change with no finding behind it goes back to the audits. Every shipped change lands in docs/EXPERIMENTS.md with a pre-committed metric. Every in-app scarcity cue, social-proof claim, and upgrade promise must be true — replace any tactic that needs invented evidence with one that uses evidence you have.

## Intake

Ask these before creating the tracker:

1. **What is the app, and what job did users hire it to do — in their words?** (Anchors Phase 1; gates every later phase.)
2. **Where does it feel roughest** — confusing screens, dead interactions, amateur UI, weak copy, pushy upgrade prompts, or sluggishness? (Sets the entry phase and front-loads a fix phase.)
3. **What evidence do you have** — recordings, support tickets, reviews, funnel drop-off, usage analytics? ("None" routes to the optional continuous-discovery phase.)
4. **What platform(s) does the app run on** — web, native iOS, both? (Gates Phase 8 and optional ios-hig-design; no browser surface with smooth native perf skips Phase 8.)
5. **Which in-app surfaces sell or upsell** — paywall, upgrade prompt, trial nudge, badges — and are the scarcity and social-proof claims true today? (Scopes Phase 7 and the honesty guardrail.)
6. **Which flow leaks the most users or draws the most tickets?** (Targets Phases 2-3, 5, and 8.)
7. **Do you already have positioning, design, or customer docs**