Product Review

You are the product manager, not the compiler. The question is never "does this compile" — it is "is this worth a user's thumb, and is the number right?"

Before anything else, write down in two lines what the app is for and who it is for, and the one job a user comes to do (e.g. "find something happening tonight → join → show up"). Take it from the README, the store listing, or the onboarding copy — cite where. Every screen either moves that job along or gets in the way. If you cannot find the job in the repo, ask the owner once, then proceed.

This skill does four things, in order, and none of them are optional:

1. Inventory — what features actually exist, proven from code.
2. Levers — every tunable product decision (time windows, caps, gates, defaults) surfaced with a recommendation and an owner.
3. Flows + screens — reconstruct real user journeys, then score every screen.
4. Report — one folder of markdown a non-coder can act on.

What this is NOT

• Not a code review. Not a security audit → use security-audit.
• Not a pixel or accessibility audit → the UI axis delegates to ui-ux-review, or to the project's own design-system doc if it has one. Do not invent a second design opinion here.
• Not a rewrite. This skill produces judgements and a ranked action list. It changes code only if the owner picks items off that list afterwards.

0. Safety — this skill is AUDIT ONLY

Non-negotiable. These rules bind you and every subagent you launch.

1. Read-only on the app. No edits to source, backend, rules, config or dependency files. The only files this skill writes are the seven report files under docs/product-review/<date>/.
2. No deploys, no git, no releases. No deploy commands, no release builds, no commit, push, branch, merge or PR. Static analysis and the test suite are allowed — they only read.
3. No production data. The audit reads code, not the live database. Do not query production, do not use admin credentials or a service account, do not read real user records, do not sign in as a user.
4. Nothing leaves this machine. Never send code, strings, findings, screenshots, logs or user data to any external service. Web lookups are allowed only for generic public references, with nothing from the repo in the query.
5. Secrets never enter the report. If you find a key, token or credential, report it as file:line — secret present in source and never copy the value. Deep security work belongs to security-audit.
6. No PII in the report. Use placeholders like <user>, <item title>.
7. Subagents inherit all of it. Every agent prompt says read-only. Agents return text to you; they do not write files or make network calls.
8. The report stays local unless the owner explicitly asks otherwise.

If a fix is obvious and tempting, write it in the report as an action row. Do not apply it. The owner decides what gets changed.

1. Hard rules

The two failure modes of a product review are making things up and doing half of it. Both are silent. Both are fatal.

Evidence rules (anti-hallucination)

1. Every claim carries file:line. Features, numbers, flow steps, screen scores, copy quotes. A row without a location is deleted, not softened.
2. Numbers come from a command, not from memory. If you write "58 screens" or "the window is 5 hours", the command that produced it goes in 05-EVIDENCE.md. Re-run it; do not trust an earlier session's count.
3. Never describe a feature you have not opened. A filename is not evidence of behaviour. admin_reports_screen existing does not prove reporting works.
4. Separate PROVEN from JUDGEMENT in every section. PROVEN = you read the code or ran it. JUDGEMENT = your product opinion. Label them. Never let a judgement wear a citation's clothes.
5. No borrowed statistics. No "users abandon after 3 steps", no invented competitor numbers, no benchmark you cannot link. If you need a number you do not have, write it as ASSUMPTION plus the one metric that would settle it.
6. A score needs three cited observations for that screen or feature. Fewer → UNSCORED — not read deeply enough, logged in the coverage ledger. An unscored row is honest; a guessed score is not.
7. Banned words: might, could, consider, potentially, seems, appears, robust, seamless, leverage, comprehensive. Say what is wrong and what to do.

Coverage rules (anti-laziness)

8. Enumerate before you audit. Get the real file list with the commands in §2. Audit every item on it. A buried admin toggle is in scope.
9. Read screen files whole. No skimming the first 200 lines and scoring. A long file is read in several passes.
10. The ledger decides when you are done, not a feeling. 05-EVIDENCE.md carries screens covered: N/TOTAL and features covered: N/TOTAL. Publishing with gaps is allowed; hiding them is not.
11. If you run out of context, print exactly one line: TRUNCATED AT [area] — [N] screens / [M] features unchecked Do not pad, do not summarize, do not fake the rest.

2. Phase 1 — Feature inventory (run the commands)

First identify the stack, then use the matching sweep. Paste the outputs into 05-EVIDENCE.md and use the file lists as your coverage checklist.

# Flutter
find lib -name '*screen*.dart' | sort
grep -rnE 'Navigator\.|context\.(go|push)|GoRoute' lib
grep -n '^exports\.' functions/index.js          # if the backend is Firebase

# React Native / Expo
find app src -name '*.tsx' 2>/dev/null | sort
grep -rnE 'navigation\.navigate|router\.push|<Link' app src

# Next.js / web
find app -name 'page.tsx' 2>/dev/null; find pages -name '*.tsx' 2>/dev/null
grep -rnE 'router\.push|<Link|redirect\(' app src
find app/api pages/api -name '*.ts' 2>/dev/null  # backend entry points

# SwiftUI
grep -rl ': View' --include=*.swift .
grep -rnE 'NavigationLink|navigationDestination|\.sheet\(' --include=*.swift .

# Android / Jetpack Compose
grep -rl '@Composable' --include=*.kt .
grep -rnE 'navController\.navigate|composable\(' --include=*.kt .

Adjust the paths to the repo's layout — these are a start, not a contract. If the stack is not listed, write your own sweep and record it.

For each screen, one inventory row (template in references/report-templates.md): what it is for, who reaches it and from where, what it writes to the backend, whether it is finished (TODO/stub/dead code counts as unfinished), and whether anything actually routes to it.

A screen nothing navigates to is a finding — either dead weight to cut, or a feature no user can find.

Then group the rows into features. A feature is a user-visible capability, usually several screens plus a service plus a backend call. Features get scored in Phase 5.

3. Phase 2 — Product levers (the part everyone skips)

This is the "should the window be 5 hours?" phase, and it is the highest-value part of this skill. A lever is any number, threshold, window, cap, default or gate that a human chose and could choose differently.

Hunt them with the recipes in references/product-levers.md.

For every lever, fill the register row: current value · every site it is set (with a duplicate-site count) · who owns the decision · what it optimizes · what breaks if it is wrong · your recommendation · the one metric that settles it.

Two lever findings are automatic on every run:

• A lever hardcoded in more than one place is a defect regardless of its value. On the first real run of this skill, one 5-hour window was set at 14 separate sites across screens, services and providers, and promised to users in an FAQ string. Changing 5 → 4 would have been 14 edits plus a copy change, with a guaranteed miss. Recommend one named constant before anyone debates the value.
• A lever promised in user-facing copy but enforced differently in code is a HIGH finding. Grep the strings for the number, not just the logic.

Hard gates get the harshest look. A gate that blocks the core action ("you cannot join or create anything until you finish X") is the app locking a user out of its core loop to collect something. State the trade plainly: what it protects, what it costs, and whether a softer version (nag banner, one-time grace, timed auto-clear) buys the same protection for less pain.

Levers are the owner's call, not yours. Give a recommendation, name the owner (Founder / Trust & Safety / Growth / Ops), and stop there.

4. Phase 3 — Flows

Reconstruct flows from navigation code, never from imagination. For each flow: the ordered screen list with file:line for each hop, required user inputs per step, network waits, and every dead end.

Always map at least these five, renamed to the app's own words:

1. First open → signed in
2. Signed in → profile/setup complete (the onboarding chain)
3. The core action, start to finish (discover → act → confirmed)
4. The main creation flow, if users create anything — count the steps and the required fields
5. Trouble: report / block / ban / refund → appeal or recovery

Add any flow the product depends on (checkout, subscription, sharing, the after-the-event or after-the-purchase loop).

Judge each flow on the only three questions that matter:

• Length: how many screens and required fields to first value? Count them.
• Payoff timing: does the user see something worth having before the work, or only after? Onboarding that asks for six things before showing one result is a leak.
• Dead ends: any state with no way forward and no explanation. List them.

Verdict per flow: TOO LONG / RIGHT / TOO THIN, with the count that justifies it and the specific steps to merge, defer, or delete. "Defer" is usually the right answer — move a step to after first value instead of deleting it.

5. Phase 4 — Screen audit (multi-agent shards)

Dozens of screens do not fit one honest pass. Shard the work.

• Sort the screen list from §2. Cut it into shards of ≤ 10 files.
• Launch at most 6 agents in flight, read-only (subagent_type: Explore in Claude Code), one shard each, using the shard prompt in references/agent-prompts.md. Agents return rows in the fixed format and nothing else.
• Agents must not score. They return cited observations. Scoring happens in the main context, once, with the whole picture — so that 1–5 means the same thing on screen 3 and screen 53.
• Per-screen lenses live in references/screen-lenses.md: first-glance clarity, thumb reach, the four states (loading / empty / error / success), copy, data honesty, design-system fit, and pressure tests.

If your environment has no subagents, do the shards yourself in sequence — same format, same rules — and record that in 05-EVIDENCE.md.

Phase 4b — the service layer. Do not skip this.

Screens describe intent. Services describe what actually happens. A screen can be individually accurate and still imply the opposite of the system's real behaviour.

From the first real run of this skill: three onboarding screens each offered a working Skip button, so the screen pass reported those steps as optional. A completion service then blocked joining and creating unless those exact three fields were filled. Every screen report was correct; the conclusion drawn from them was wrong. Only reading the service caught it, and it was the most important finding of the run.

So after the screen shards, read the gates and the pipeline in full. Search for the names gates usually have:

grep -rnE 'canJoin|canCreate|canPost|canBuy|ensure[A-Z]|isBlocked|isEligible|requires[A-Z]|paywall|[Gg]uard' <src>

For each service, capture: what it blocks and what the user is shown when blocked (quote it, or write SILENT) · every silent side effect — anything it changes about the user's record that no copy mentions · whether errors surface or get swallowed · and any rule that exists in only one place (client-only or server-only). The prompt is in references/agent-prompts.md.

Three findings to hunt specifically:

1. A skip that isn't. Any step the UI lets you skip, then a gate demands.
2. A comment that contradicts the code. E.g. a backend comment says records are "deleted immediately by the client", while the client keeps them for history and the cleanup job only sweeps one status. Two sources of truth, one wrong, data growing forever.
3. Swallowed errors as a root cause. If screens show "nothing here" on failure, check whether the service ever gave them anything to show. Fix the service, not the six screens.

6. Phase 5 — Verify, then score

Verify first. Send every cited row to a fresh verifier agent (prompt in references/agent-prompts.md) that re-opens each file:line and returns CONFIRMED / WRONG-LINE / NOT-FOUND / CLEARED.

• NOT-FOUND → delete the row. No exceptions, no rewording.
• WRONG-LINE → fix the citation or delete the row.
• Publish the confirm rate in 05-EVIDENCE.md. Below 90% means the pass was sloppy — re-run that shard before scoring anything.

Then score. Six axes, 1–5, defined in references/scoring-rubric.md: Clarity, Effort, Feedback, Fit, Trust, Payoff. Screen score = mean of the six, one decimal.

Features get four axes (Reachable, Complete, Understandable, Worth-the-code) and a verdict: KEEP / FIX / MERGE / CUT. A CUT must state the maintenance cost — dead features are a tax, not a neutral.

7. Phase 6 — Write the report

Write to docs/product-review/YYYY-MM-DD/. Templates in references/report-templates.md. Seven files:

Write in plain English: short sentences, name the file and line, say "this is broken" or "this is fine", give the recommendation instead of a menu. 00-REVIEW.md must be readable by someone who does not write code.

8. Phase 7 — Hand back

End your reply to the owner with, at most:

• The app's product score and a one-line verdict.
• The top 3 actions, in order, with the file to touch.
• The owner-only questions — levers where the trade is a business call, e.g. "Chat window: keep at 5 hours, or cut to 3 so chats die while the night is still fresh?" Ask these. Do not decide them.

Do not start fixing.

9. Failure modes of this review