Thumb First

Thumb-First · Mobile Review (umbrella)

The one-stop entry point for the thumb-first mobile suite. It coordinates two independently-maintained sibling skills and merges their output:

The two layers have different shelf-lives — design judgment is durable; platform specifics rot with each OS/browser release — so they live as separate skills and are versioned independently. This umbrella is the seam that runs both and reconciles them. Keeping the two finding classes visually distinct in the merged report is the whole point: never let an opinion read as a defect, or a must-fix read as a preference.

---

Mode Selection

Detect from $ARGUMENTS, else default to full review.

For design-only or platform-only, hand off to that sibling skill and stop — don't run the merge.

If the user picked a review but gave nothing to review, ask what they're reviewing — a screenshot, a live URL, code, or a description — before routing. Both passes can work from any of these; they just need one.

---

Full Review — Orchestration

Read `workflows/full-review.md` and follow it. The shape:

Step 0 · Detect the target once

Sniff the repo for web/PWA (next.config, vite, web manifest, service worker) vs native (react-native/expo, app.json, ios/+android/, *.swift, pubspec.yaml); if ambiguous, ask. Pass the result to both passes — the platform pass branches hard on it (see thumb-first-platform Step 0; native triggers handoff or an honest limitation, never a faked web audit).

Step 1 · Design pass

Run thumb-first-design's audit (../thumb-first-design/workflows/audit.md, loading ../thumb-first-design/references/designer-lenses.md). Produces design findings + the silently-decided forks. This layer applies to every target.

Step 2 · Platform pass

Run thumb-first-platform's audit path (../thumb-first-platform/workflows/audit-mobile-pwa.md) for web/PWA, or take its native branch (handoff / stated limitation). Produces objective defects with file:line and P0–P3.

Steps 1 and 2 are independent — run them as two parallel subagents when speed matters, then merge. Sequential in the main context is fine for small surfaces.

Step 3 · Merge

Combine into ONE report per `references/unified-report.md`:

• Design & judgment — forks and opinions, "decision needed", ranked by user impact. Distinct styling (amber/neutral).
• Platform defects — objective, P0–P3, file:line, "must fix". Distinct styling (red severity scale).
• Combined fix-order — one prioritized list interleaving both, so the reader sees what to do first regardless of class.

Base the HTML on ../thumb-first-design/references/report-template.html (the canonical report) and add the platform-defects section — don't reinvent the template.

---

What this umbrella is NOT

• It does not hold design or platform knowledge itself — that lives in the two sibling skills. This file is routing + merge only. If you're tempted to add a designer lens or a Safari quirk here, it belongs in the sibling.
• It does not write implementation. Design findings hand off to responsive-craft / RN-Expo skills; platform defects are fixed by thumb-first-platform's fix workflows.

Suite Map

thumb-first/            ← this umbrella (routing + merge)
thumb-first-design/     ← design judgment (8 lenses, forks) — platform-agnostic
thumb-first-platform/   ← technical verification (web/PWA deep, native handoff)

Reference & Workflow Index

Unified Report — Merged Output Structure

The one-stop review produces a single self-contained HTML report. Its defining job: present two fundamentally different kinds of finding without letting them blur together. An opinion must never read as a defect; a must-fix must never read as a preference.

Base template

Start from ../thumb-first-design/references/report-template.html — the canonical thumb-first report. It already ships the merged-review sections as a worked example: a Fix order section right after the header and a Platform defects section after the findings, plus all their CSS and the documented steel platform channel (--plat) and P0–P3 ramp. So you are populating these sections, not building them — replace the worked-example content, keep the structure, classes, and CSS. A design-only audit deletes both sections; a full review fills them in. Do not reinvent the markup or restyle the channels.

The template ships a pure-CSS Dark / Light toggle (top-right of .wrap) with a full :root:has(#theme-light:checked) light-mode token set — the merged report inherits it for free. Keep the toggle markup and both token blocks; if you re-sample the adaptive accent, set its dark and light value. See ../thumb-first-design/references/output-format.md → "Dual theme (light / dark)".

The two finding classes (keep visually distinct)

Class A — Design & judgment

• Source: the design pass (thumb-first-design).
• Nature: subjective; often a fork with more than one valid answer.
• Severity vocabulary: Critical / Important / Polish (user-impact), plus "Decision needed" for forks.
• Styling: the report's existing amber/neutral lens-and-fork treatment. Forks render as option cards with tradeoffs, not as bugs.
• Label every item with the lens that caught it (Hoober, Hurff, Clark, …).

Class B — Platform defects

• Source: the platform pass (thumb-first-platform), web/PWA targets.
• Nature: objective; right-or-wrong.
• Severity vocabulary: P0 / P1 / P2 / P3.
• Styling: a distinct red severity scale section, clearly separated from Class A. Each defect carries file:line and a concrete fix.
• If the target was native: this section is replaced by a short handoff/limitation note (which native skill to use, or that native audits aren't covered) — never fabricated web defects.

Use a visible structural divider and different badge shapes/colors between the two classes. A reader skimming on a phone must be able to tell at a glance whether a row is "a decision I should make" or "a bug I must fix."

The combined fix-order (the reconciliation)

After the two class sections, add one interleaved priority list — the single most useful artifact of running both passes together. Rank across both classes by real user impact:

1. [P0 · defect]   Safe-area inset missing → content under the home indicator        thumb-first-platform · file:line
2. [Critical · design] Primary action sits in the top "Ow" zone — move to lower band  thumb-first-design · Hoober
3. [P1 · defect]   100vh overflow on the game screen                                  thumb-first-platform · file:line
4. [Important · fork]  Tab bar vs. bottom sheet for navigation — decision needed      thumb-first-design · Rausch
…

Keep the class tag (defect / design / fork) and source on every line so the priority list never erases the distinction — it orders across classes without merging them.

Sections, in order

1. Header — what was reviewed, target (web/PWA or native), device class, date, counts (N design findings · M forks · K platform defects). 2. Combined fix-order — the interleaved list above (lead with it; it's what the user acts on). 3. Design & judgment — Class A, full detail (lens reads, forks with options). 4. Platform defects — Class B, full detail (file:line, fix), or the native handoff note. 5. What I couldn't assess — limits of each pass (e.g. "kid-hand reach is adult-grip data"; "no real-device test run").

Anti-goals

• Don't average the two severity scales into one number — P0 and "Critical" are different currencies; show both, don't fuse.
• Don't bury the platform defects inside the design narrative or vice versa.
• Don't let the umbrella restate design or platform content — link to / invoke the siblings; this report only arranges their output.

Full Review — Orchestration

Runs the design pass and the platform pass over the same mobile target, then merges them into one prioritized report. This is what /thumb-first does by default.

Required Reading

• This file.
• references/unified-report.md — the merged output structure.
• At run time you will load, from the sibling skills:
• ../thumb-first-design/workflows/audit.md + ../thumb-first-design/references/designer-lenses.md
• ../thumb-first-platform/workflows/audit-mobile-pwa.md (web/PWA) — or take its native branch.

Step 0 · Establish scope and detect the target

1. Confirm what's being reviewed: a screenshot, a live URL, code/repo, or a description. If nothing was provided, ask. One is enough. 2. Detect the target platform (do this once; both passes need it):

• Web / PWA → next.config.*, vite.config.*, index.html, web manifest.json/manifest.webmanifest, a service worker.
• Native → react-native/expo in package.json, app.json/app.config.*, an ios/+android/ pair, *.xcodeproj/Package.swift/*.swift, or pubspec.yaml.
• Ambiguous / both → ask which target to review.

3. Note the device class (phone vs tablet, iOS vs Android) — reach math and safe-area behavior differ, and both passes should know it.

Step 1 · Design pass (always runs)

Run the thumb-first-design audit against the scope. Load its designer-lenses.md, weight the lenses to the context, surface the decision forks, and produce findings ranked by user impact (critical / important / polish). This layer is platform-agnostic — it runs identically for web and native.

Capture: design findings (with the lens that caught each) and the silently-decided forks.

Step 2 · Platform pass (target-aware)

• Web / PWA → run thumb-first-platform's audit path. Produce objective defects: viewport/100vh, safe-area insets, touch targets, tap delay, service worker/offline, manifest/install, Core Web Vitals — each with file:line and a P0–P3 severity.
• Native → take thumb-first-platform's Step 0 native branch: if a native skill is installed (react-native-design, building-native-ui, vercel-react-native-skills, etc.), name it as the handoff for the native technical pass; if none, state plainly that the suite does design judgment + web/PWA technical only and does not run native-platform audits. Do not fabricate web defects for a native target.

Parallelize when it pays. Steps 1 and 2 are independent. For a large surface, run each as its own subagent and merge their structured results. For a single screen, sequential in the main context is simpler.

Step 3 · Merge into one report

Follow references/unified-report.md. Two visually distinct finding classes, never blended:

• Design & judgment — forks + opinions, "decision needed", amber/neutral styling, ranked by user impact.
• Platform defects — objective, P0–P3, file:line, "must fix", red severity scale.

Then produce a combined fix-order: one interleaved list (e.g. a P0 defect and a critical design fork both land at the top), so the reader sees what to do first regardless of class. Base the HTML on ../thumb-first-design/references/report-template.html and add the platform-defects section — don't rebuild the template.

Step 4 · Wait gate

Present the merged report and stop. Then offer next steps:

• Hand design fixes to responsive-craft / native skills.
• Hand platform defects to thumb-first-platform's fix workflows (fix-ios-issues.md, optimize-performance.md).

Success Criteria

• [ ] Target detected (web/PWA vs native) before either pass; native correctly handed off or limited, not faked.
• [ ] Both passes ran (or platform pass correctly delegated for native).
• [ ] Report keeps the two finding classes visually distinct — no opinion styled as a defect, no must-fix styled as a preference.
• [ ] A single combined fix-order interleaves both classes by priority.
• [ ] Knowledge stayed in the siblings — this workflow only routed and merged.