Cross-Platform Parity Audit Across Codebases

Tier: Advanced · Workflow area: Mobile engineering & release

This playbook produces an evidence-backed matrix of behavioral drift, ranks the gaps, and converts the worst into tickets — without any engineer holding three codebases in their head at once.

When to use

• •
  The same product feature exists in two or more codebases (native iOS + native Android; RN or Flutter app + native modules; web + mobile).
• •
  Symptoms of drift: bug reports that reproduce on one platform only, support asking "is this expected on Android?", or a platform team inheriting a feature they did not build.
• •
  Before a rewrite or platform consolidation — the matrix is the requirements document the old code never had.

Skip it when a shared core (KMP, shared TS logic) already owns the behavior in question — audit the thin platform shells only.

Prerequisites

• •
  A coding agent that can read multiple repos in one session: Claude Code launched from a parent directory containing the checkouts, or Cursor with a multi-root workspace.
• •
  The feature scoped to something auditable in a session — "checkout" or "password reset", not "the app".
• •
  A skeleton of the states that matter, from product knowledge: happy path, each validation failure, offline, session expiry, concurrent edits, locale/currency variants.
• •
  Read access to both (or all three) repos at comparable versions — audit what is shipped, not a feature branch.

The workflow

1. 1.

   Extract each platform's behavior independently first. Prevent the agent from harmonizing by asking per-platform, in separate passes:

   Copy

   In repo android/ only: trace the password-reset flow. List every
   behavior as a row: trigger, validation rules (exact limits, regexes),
   error messages shown, retry/rate-limit handling, analytics events,
   navigation on success/failure, offline behavior. Cite file:line for
   every row. Do not look at the other repos yet.
   

   Repeat for ios/ and web/. Independent extraction means a gap shows up as a genuinely missing row, not a copied assumption.

2. 2.

   Merge into the matrix. Now let it compare:

   Copy

   Merge the three behavior lists into one table: behavior | web |
   android | ios. Each cell: SAME, DIFFERENT (describe how), or MISSING,
   with the citation. Where implementations differ, do not guess which
   is intended - mark it DRIFT-UNKNOWN.
   

   The DRIFT-UNKNOWN marker is the honesty valve: which platform is "right" is a product decision, and the agent must not make it.

3. 3.

   Spot-check the cells that will drive work. Open the citations behind every MISSING and the top DIFFERENT cells yourself — five to ten checks. Agents mis-attribute behavior that lives in a shared backend, in a remote config flag, or in a library default; each of those looks like platform code drift until you read the cited line.

4. 4.

   Adjudicate drift with product, then rank. Walk the matrix with the product owner: each DIFFERENT/MISSING cell becomes intended (document it in the matrix as such), bug on platform X (ticket), or spec gap (neither platform matches intent). Rank tickets by user impact — a validation-limit mismatch that eats user input outranks an analytics-event gap.

5. 5.

   Make the matrix regenerable, not sacred. Commit the prompts and the matrix to a parity/ folder in the umbrella or docs repo. Rerun the audit after major feature work on any platform — the second run is fast because the prompts exist, and diffing matrix versions shows whether drift is shrinking. For hot features, a slimmed version of the extraction prompt can run in CI on a schedule and flag new drift rows.

Tool variants

• Claude Code from a parent directory: the natural fit — workspace/{web,android,ios} and one session that can grep all three; use subagents per platform for the extraction passes.
• Cursor multi-root workspace: same flow, with extraction passes as separate chats to preserve independence.
• Chat assistant without repo access: feasible for small features — paste the relevant files per platform in separate conversations, then merge in a third; expect to do more of the tracing yourself.
• RN/Flutter + native audits: treat the JS/Dart layer as one "platform" and each native module set as another; drift between the shared layer and a native fallback path is the classic finding.

Verification

• •
  Every matrix cell carries a citation, and your spot checks confirmed the load-bearing ones (MISSING and top DIFFERENT).
• •
  Behaviors that live in the backend or remote config are marked as shared, not platform drift — you checked the suspicious ones.
• •
  Each drift row has an adjudication (intended / bug / spec gap) and the bugs have tickets with the matrix row pasted in.
• •
  Rerunning the extraction prompt on one platform reproduces its column — the audit is deterministic enough to trust as a baseline.

Pitfalls

• Letting the agent compare in one pass. Joint extraction contaminates: it sees Android's rate-limit handling and "finds" it on iOS. Independence first, merge second.
• Auditing the UI instead of the behavior. Pixel differences are usually intended platform idiom; validation rules, error handling, data mutations and event tracking are where drift hurts.
• Trusting SAME cells blindly.SAME at the behavior-description level can hide different limits or edge handling; the exact-values requirement (limits, regexes) in the extraction prompt is what makes SAME meaningful.
• Matrix as a one-off. An unregenerable matrix is stale in a quarter; committing the prompts is what makes this an instrument instead of an event.
• Boiling the ocean. Three platforms × whole app is weeks of adjudication; one feature per audit keeps the loop under a day.

Restricted-environment variant

Multi-repo audits need broad code access, which is exactly what restricted environments limit. Options: run the whole loop on an in-tenancy agent (Bedrock/Azure-backed) with the same prompts; or degrade gracefully — have each platform team run the extraction pass locally (local model or approved tool) against their own repo, then merge the three behavior tables in a normal document review. The merge step needs only the tables, not the source.

Success criteria

• •
  The audited feature has a complete, adjudicated matrix, and the platform-only bug class for it drops to zero in the following quarter.
• •
  "Does iOS also do X?" is answered by a lookup, not an archaeology session.
• •
  Rewrites and consolidations start from the matrix as the behavioral spec, cutting discovery time from the estimate.
• •
  Reruns after major releases show drift rows trending down — the matrix is steering behavior, not just describing it.