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

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 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 (POSITIONING.md, DESIGN.md, CUSTOMER.md)? (Phases 1, 4, 6, 7 build on them.)

Phase-skip heuristics: skip Phase 8 with no browser surface and smooth native speed; skip Phase 7 with no in-app upsell surfaces; skip Phase 4 when the UI already reads cleanly in grayscale on a consistent token scale; skip Phase 6 when in-app copy is already concrete and jargon-free. Never skip Phase 1 — it aims every other phase (defer it, don't skip it). Then create docs/IMPROVE-APP-PLAN.md from the template and confirm the plan. Done when docs/IMPROVE-APP-PLAN.md exists with every phase statused and the user has confirmed the plan.

Phases

Phase 1 — Re-anchor on the job the app is hired for (jobs-to-be-done) — GATE

Purpose: Name the job users hire the app for and where it underdelivers, before any screen changes; Phases 2-9 may only fix what an audit or finding in Phases 1-3 flags.

Brief (fallback): Customers hire a product to make progress in a circumstance. State the job as "When [situation], I want to [motivation], so I can [outcome]" — never naming the app; every job has three dimensions (functional, emotional, social), and omitting one loses why users stay. Track first use vs repeated use (Big Hire vs Little Hire), and map alternatives including non-consumption and improvised workarounds.

Invoke: Use the jobs-to-be-done skill with the app, its usage data, and the roughest flow from intake. Ask for the job statement, the three dimensions with where the app underdelivers on each, and the alternatives users switch to.

Decide with the user: (1) Confirm the job statement reads without the product name. (2) Which underdelivered dimension is worst — functional, emotional, or social? (3) Is the leak a Big Hire (onboarding) or Little Hire (daily use) failure?

Artifact: Extend docs/CUSTOMER.md ## Job Statement, ## Job Dimensions (functional/emotional/social, each with its underdelivery note), and ## Competing Alternatives (alternative | why hired | weakness, incl. non-consumption). Update the tracker.

Done when: the job is stated without the product name, all three dimensions carry an underdelivery note, alternatives are logged, and Phase 1 shows done — only then are Phases 2-9 unlocked.

Phase 2 — Remove the friction that makes users think (ux-heuristics)

Purpose: Cut cognitive load on the flows that leak users — find where the interface makes people stop and puzzle.

Brief (fallback): "Don't Make Me Think" — users scan, satisfice, and muddle through. Run a heuristic evaluation against Nielsen's 10 heuristics; rate each issue 0-4 and order by severity × how often users hit it, so catastrophes outrank cosmetics. Apply the Trunk Test to key screens (what app, what screen, my options, where am I, where's search?), cut half the words then half again, and fix forms with inline validation and error messages that say what, why, and how.

Invoke: Use the ux-heuristics skill on the highest-leak flow with the Phase 1 job and dimensions. Ask for a severity-rated evaluation, a Trunk Test result per key screen, and rewritten label, form, and error copy.

Decide with the user: Which severity-4 and -3 issues get fixed now versus backlogged? Confirm fixes run by severity × frequency, not by ease.

Artifact: Extend docs/DESIGN.md ## UX Audit Findings (issue | heuristic | severity 0-4 | fix | status); append each fix to docs/EXPERIMENTS.md ## Experiment Backlog with ICE. Update the tracker.

Done when: every issue carries a 0-4 severity and a fix, the Trunk Test passes on each key screen or is logged, and severity-4 issues have an owner.

Phase 3 — Design out the errors (design-everyday-things)

Purpose: Make the wrong action hard and every outcome legible — where users act wrong, the design misled them, not the user.

Brief (fallback): There is no human error, only bad design. Bridge two gulfs: Execution ("how do I do this?") with clear signifiers and constraints (date picker over free text, Submit disabled until valid); Evaluation ("what happened?") with feedback under 0.1s and visible system state. Distinguish slips (right intent, wrong action) from mistakes (wrong intent); prefer undo over are-you-sure dialogs, and write error messages that say what went wrong and how to fix it, never blame.

Invoke: Use the design-everyday-things skill on the core flows (onboarding, the primary action, destructive actions). Ask for weak signifiers, where a constraint makes an error impossible, feedback gaps, and message rewrites.

Decide with the user: Where should a constraint replace an error message, and where should undo replace a confirmation dialog?

Artifact: Extend docs/DESIGN.md ## UX Audit Findings (heuristic = Norman gulf; issue | severity 0-4 | fix | status); append fixes to docs/EXPERIMENTS.md ## Experiment Backlog. Update the tracker.

Done when: each core flow has signifier/constraint/feedback fixes logged, error messages meet the what/why/how checklist, and destructive actions offer undo.

Phase 4 — Make it look as clear as it works (refactoring-ui)

Purpose: Give the screens a professional visual hierarchy so nothing amateur undercuts the flows you just fixed.

Brief (fallback): Great UI is systems, not talent. Design in grayscale first: establish hierarchy with size, weight, and contrast before any color — combine levers, don't multiply (all three only for the one hero element). Enforce a spacing scale (4/8/16/24/32/48/64) where gaps between groups exceed gaps within them; constrain text to 45-75 chars and forms to 300-500px. Add color last: 5-9 shades per hue, grays tinted, not pure black.

Invoke: Use the refactoring-ui skill on the key screens with the Phase 2-3 findings and current design tokens. Ask for a grayscale hierarchy pass, spacing-scale corrections, a systematic palette, and the exact token/CSS changes.

Decide with the user: Fix within the current design system or introduce new tokens? Confirm color work waits until the grayscale layout reads.

Artifact: Extend docs/DESIGN.md ## Tokens (spacing scale · palette shades · shadows) and ## Components (component | decision | status); append fixes to docs/EXPERIMENTS.md ## Experiment Backlog. Update the tracker.

Done when: the key screens read in grayscale, the spacing scale is applied, one primary action dominates each screen, and the token decisions are recorded.

Phase 5 — Make every action feel alive (microinteractions)

Purpose: Give the moments users touch every day the feedback that separates a product they tolerate from one they love.

Brief (fallback): Every microinteraction has four parts — Trigger, Rules, Feedback, Loops & Modes. The common failure is missing or late feedback: direct manipulation needs a response under 100ms, usually by animating the element the user touched (a button depresses to "Saving…"), not a separate toast. Map every state — empty, loading, partial, full, error, disabled — and use the least feedback that communicates, scaled to the event's significance.

Invoke: Use the microinteractions skill on the most-used interactions (save, submit, toggle, delete, load). Ask for a Trigger/Rules/Feedback/Loops audit, the exact feedback each needs, a full state map, and one signature moment.

Decide with the user: (1) Which interactions to polish first. (2) The one signature moment worth extra craft — apply the removal test: would the product feel materially worse without it?

Artifact: Extend docs/DESIGN.md ## Microinteraction Inventory (interaction | trigger/rules/feedback/loops | fix | status); append fixes to docs/EXPERIMENTS.md ## Experiment Backlog. Update the tracker.

Done when: each audited interaction has its four parts and required feedback logged, every state is mapped, the signature moment passes the removal test, and fixes are rows with status.