The /mobile-audit audit
Every page has to work on a phone. This audit points a real browser at yours at 375px and finds where they don't: tap targets too small, layouts that scroll sideways, text that crushes, performance that only shows up on a throttled connection. It finds; the fixing is a separate job.
Raw mobile critics throw false positives, so every serious finding gets attacked before it reaches the report. If the verify step feels like overkill, tell us. Reply on LinkedIn.
How to read this map
Pick a stage to walk, or start at the top
The walkthrough, as text
Every stage of the interactive walkthrough above, as plain readable text. Each stage has its own link.
Stage 0Point it at somethingA page, a module, or all
Scope
You tell the audit what to check in plain words, one page, a section, or the whole app, and it works out the routes. A big sweep is dozens of captures and critics, so it stops and confirms the cost before it starts.
Infer the scope from your words, enumerate the routes, and gate a heavy full-app sweep behind a cost confirmation.
What happens
Name a page and it checks that page; name a section and it checks that section; say the whole app and it enumerates every route. Left empty, it defaults to the routes you just changed.
A light run of a few routes goes ahead inline. A heavy run, a whole section or the whole app, means capturing many routes and fanning out critics, so it shows the count and asks before proceeding.
Who acts
- AskUserQuestion, command: The cost gate before a heavy, many-route sweep.
The rules
- Scope comes from your words. No flags; the audit reads the scope from plain language and defaults to your changed routes.
- Heavy sweeps are gated. A many-route run confirms the cost first, so an ambiguous prompt can't spawn a huge job by accident.
In: A plain-language scope. Out: A route list and a light-or-heavy weight.
Stage 1Shoot each page at 375pxOne browser, saved to disk
Capture
A real browser visits each route at phone size, in one sequential session, and saves a screenshot and a snapshot of each. It captures the default view, the one a user lands on, not a page with menus already open.
One browser captures each route at 375px to disk. It measures the default rendered state, not an opened drawer.
What happens
The runtime layers share one browser, so capture is sequential by nature. Each route gets a full-page screenshot saved to disk, because the critics that judge it later can only read a file, never an inline image.
It captures the default state deliberately. Measuring a page with the nav drawer open once inflated the count of tiny tap targets across every route, so off-screen and hidden controls are excluded and the shot reflects what the user sees first.
Who acts
- the browser, tool: Visits each route at 375px and saves a screenshot and snapshot.
The rules
- Screenshots to disk. Findings are judged from saved files, so every capture is written to disk, then pruned after the report.
- Capture the default state. No opening drawers or menus first; the shot and the measurements reflect the first view.
In: The route list. Out: A screenshot and snapshot per route, on disk.
Stage 2Four ways to be wrongStatic, measured, throttled, used
Four layers
Each captured page is read four ways. The source is grepped for known traps. The rendered page is measured for real. It's scored under a throttled phone connection. And two critics judge whether it's actually usable with a thumb.
Four layers per page: a static source scan, a runtime measurement, a throttled performance score, and a mobile-usability critique.
What happens
The static layer greps the source for buttons under the minimum size, inputs missing mobile hints, hover-only interactions, and fixed widths wider than the screen. The measured layer checks the rendered reality: real tap-target sizes, whether the page scrolls sideways, inputs small enough to trigger zoom. The measured layer wins where the two overlap.
The throttled layer scores the page on a slow connection and a slowed processor, because a phone-width page on a fast desktop hides the performance failures phones actually hit. The fourth layer is two critics: one for whether the visual hierarchy survives at phone width, one for whether the primary action is reachable with a thumb without hunting or sideways scrolling.
Who acts
- design + mobile-UX critics, agent: Judge whether the page is usable at phone width, not just technically correct.
- the measured collector, tool: Measures the rendered page and scores it under throttle.
The rules
- Measured beats static. Where a source heuristic and a live measurement disagree, the measurement of the rendered page wins.
- Throttle is the point. Performance is scored on a slow connection and processor, because full-speed desktop hides what phones hit.
In: The captured pages. Out: Findings from four layers per route.
Stage 3Attack the serious findingsCut the false positives
Verify
Raw mobile critics cry wolf, so every high-severity finding is re-checked before it reaches the report. A verifier looks at the screenshot and the source and asks: is this real, or a misread? On doubt, it's refuted. And a problem on every page is marked as one shared fix, not counted against each page.
Verify every high-severity finding against the screenshot and source, defaulting to refuted; mark shared problems systemic, not per-page.
What happens
Each high finding gets its own verifier, which re-checks the claim against the saved screenshot and the cited source: is that redirect actually broken or intentional, is that table really clipping or just scroll-contained, is that target really under size. Uncertain findings are refuted, and the refuted count is the run's false-positive signal.
The load-bearing move: a finding that repeats on most routes with near-identical evidence, the same nav chips too small on every page, is one shared-component fix, not a rework per page. Tagging it systemic keeps a single shared problem from condemning the whole app.
Who acts
- per-finding verifiers, agent: Re-check each high finding; refute on doubt.
The rules
- Refute on doubt. A high finding that can't be confirmed against the screenshot and source is refuted, so false positives never reach the report.
- Systemic once, not per page. A shared-component problem on every route is one fix; it must not force every page to rework.
In: The four-layer findings. Out: Verified findings, false positives cut, shared issues tagged systemic.
Stage 4Works, minor, or reworkOne verdict per page
Verdict
Each page gets a plain verdict on its own page-specific issues: green if it works, yellow if it needs minor in-place fixes, red if it has a real problem or just isn't usable on a phone. Shared problems are counted once, not held against every page.
Each route gets a works, minor, or rework verdict, judged on its page-specific issues with systemic ones counted once.
What happens
Green means no page-specific high finding and at most a minor issue. Yellow means some medium issues, fixable in place. Red means a real page-specific high finding, or a page that simply isn't usable on a phone.
The verdict is judged on what's specific to each page. A systemic problem is counted once against the shared component, so one shared bug doesn't paint every page red.
Who acts
- the triage, agent: Assigns each route a works, minor, or rework verdict.
The rules
- Judged on page-specific issues. A route's verdict reflects its own problems; shared issues are counted against the shared component, not the page.
In: The verified findings. Out: A works, minor, or rework verdict per route.
Stage 5Write it down, hand it offA doc, then the fixer
Write-up
With your go-ahead, the audit writes up what it found: a short doc for a page or two, or a phased campaign for a whole app, ordered shared-fixes-first. Then it stops. The fixing is a separate pipeline; this one never edits a page.
Write the findings to a doc or a phased campaign, gated on your approval, and hand each fix to the implement pipeline.
What happens
A light run produces a short audit doc with per-page findings and their fixes. A heavy run produces a phased campaign, a triage table at the top and phases ordered systemic-first, each step pointing at the implement pipeline.
That hand-off is the boundary. This audit is diagnostic only; it never fixes anything itself, and after writing the durable text record it prunes the transient screenshots.
Who acts
- AskUserQuestion, command: The gate before writing: write it, surface inline, or re-run a layer.
- page-implement, skill: The fixer each finding is handed to; the audit never fixes.
The rules
- Diagnostic only. The audit writes findings and hands fixes to the implement pipeline; it never edits a page.
- Systemic-first ordering. A campaign fixes the shared problems first, since one shared fix can flip many pages green at once.
In: The per-route verdicts. Out: An audit doc or a phased campaign, fixes handed off.
Stage ✓A phone-readiness verdict you can trustFound, verified, handed off
Triaged
What you end with is an honest read of how your pages hold up on a phone: every serious finding verified, shared problems separated from page-specific ones, and a clear verdict per page, ready to hand to the fixer.
The audit trades a fast look for a trustworthy one: four layers in, verified verdicts out, fixes handed off.
What happens
Every high finding was attacked before it reached you, shared problems were counted once, and each page got a plain verdict. That is the difference between a real triage and a pile of mobile nitpicks.
The fixes go to the implement pipeline, which has its own field guide. A saved phone-width baseline then guards against the same problems creeping back.
The rules
- Trust over speed. The value is that the findings are verified and de-duplicated, so the verdict per page can actually be acted on.
In: A set of pages. Out: A verified, per-page mobile verdict, fixes handed off.