Troubleshooting playbook

Turns an error into a proven fix fast, on iOS and Android: look the failure up in a catalogue of about 460 known React Native 0.86 / Expo SDK 57 / Xcode / Gradle / Jest / Metro / EAS / Maestro failures, red boxes and run-time faults (each with symptom, cause, fix, status, platform and the skill that owns the procedure), apply the fix at its cause, prove it with the command that failed, scan the repo for failures that are visible in files before they happen, and record anything new so the next session finds it in seconds.

Rules that must hold

1. Look it up before you diagnose. Run find-fix.mjs with the exact first error line before touching code. Many fixes here are counter-intuitive (a Metro cache that ignores the variant, a frame clock that resets, a polyfill that lacks throwIfAborted) and were expensive to find; guessing repeats that cost.
2. Fix the cause, never the check. No widened tolerance, skipped or deleted test, eslint-disable, raised limit, regenerated golden or loosened version to make a failure go away. A green gate over a real bug ships the bug.
3. Rows that need a human are stops. Keychain, agreements, licences, 401/403, a missing store record, signing keys, sudo, consoles and product decisions: send one message (the step, the exact error line, the one action needed) and wait. Retrying can lock an account or burn build numbers, and the decisions are not the agent's.
4. When an entry names a skill, load that skill for the fix. The catalogue gives the diagnosis; the owning skill has the procedure, templates and checks that prove the fix.
5. A fix is proven only by rerunning the command that failed, then the area's gate. "The error went away once" is not evidence; the same command passing, and then npm run -s check:fast, npm run verify, the simulator or emulator build, or the release gate, is.
6. Treat open entries as the current fallback, not as settled facts. Apply their fix, say in the report that the behaviour is unverified, and never present it as proven.
7. Record every newly solved failure in assets/known-failures/<area>.json and its first error line in assets/known-queries.tsv, never in the rendered references. Then run check-catalogue.mjs --write. When the cause is visible in repo files, add a rule to scripts/lib/pitfalls.mjs with a planted-bug case, so the scanner catches it before it happens.
8. Change one thing at a time; after three failed hypotheses, stop and report what was tried and what the evidence shows. A pile of simultaneous changes hides the cause, and a stuck report beats a clever workaround.
9. Never destroy evidence or other sessions' state to "start clean". No xcrun simctl erase|shutdown|delete all or booted, no xcode-select -s (select Xcode per process with DEVELOPER_DIR), no adb without -s <serial>, no adb kill-server or ./gradlew --stop, no wiping caches or node_modules before the cause is known; clean only your own build folder and the simulators and emulators you created (<project>-<purpose>).
10. Versions decide facts. Read the installed source in node_modules/ before trusting memory or docs; a version-bound entry carries appliesTo, and find-fix.mjs . ranks entries for other versions lower and says so. Training data uses APIs this stack deprecates or replaces (runOnJS -> scheduleOnRN, .value -> .get()/.set(), Skia.Path.Make() -> Skia.PathBuilder) and versions it cannot take yet (Jest 30, ESLint 10).

Workflow