SuperAPI AI Directory
Partner中文AI newsFavorites
Skillstroubleshooting-playbook

troubleshooting-playbook

Coding & development

View repository

Updated 10-18 18:02

About this skill

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

  1. Capture the first error line (not the last), the command that produced it, and the platform. The logs on both platforms are listed in references/diagnosing-new-failures.md ("Where the evidence is").
  2. Look it up: node ${CLAUDE_SKILL_DIR}/scripts/find-fix.mjs . --text "<first error line>" from the repo root. Also try two or three plain words for what you see ("banner never appears"), --log <file> for a whole log (error patterns only), --id <id> for an id another checker printed, --platform ios|android to drop the other platform's entries. Every MATCH and MATCH? prints the cause, the fix, the status, the platform and the owning skill.
  3. Act on the match. Only a MATCH line (an error pattern matched) is a diagnosis. A MATCH? line matched words only: confirm its symptom against what you see before acting on it, and treat it as no match when it does not fit. Marked stop and ask a human (only ever on a MATCH): send the stop message and end the step. Names a skill: load it and apply the fix with its procedure. Otherwise apply the fix directly. The full table of each area is its reference (below); read it when the match is close but not exact.
  4. No match, or the fix did not work: follow the loop in references/diagnosing-new-failures.md: reproduce cleanly, change one thing at a time, suspect the newest change first, make a minimal repro in a scratch copy for library bugs.
  5. Scan for known pitfalls before a first device build, a release, a dependency or SDK bump, and whenever failures repeat: node ${CLAUDE_SKILL_DIR}/scripts/check-known-pitfalls.mjs . from the repo root. Each FAIL line names the file, the catalogue id, the fix and the cause; fix and rerun until RESULT: PASS. It reads paths through the repo layout (src/, scripts/, .maestro/, contracts/; rn-skills.config.json keys srcDir, scriptsDir, e2eDir, configDir, servicesDir, contractsDir, and package.json workspaces when multi-package), and two repo facts owned by other skills: contracts/ads.json audience (admob-ads-and-consent; a child-directed app needs no tracking plugin) and contracts/rtl.json directionSource (rtl-and-direction; the device profile tolerates supportsRTL).
  6. Verify: rerun the failing command, then the area's gate.
  7. Record: add or correct the entry (field rules in the diagnosing reference), add <id><TAB><first error line> to assets/known-queries.tsv, run node ${CLAUDE_SKILL_DIR}/scripts/check-catalogue.mjs --write, then check-catalogue.mjs without flags. If you added a pitfall rule, add its bad-<id> case to tests/fixtures/check-known-pitfalls/CASES.json (its ops and its "expect" lines: the rule id and the planted file:line). Then run node ${CLAUDE_SKILL_DIR}/scripts/selftest.mjs.
  8. Report in plain words (git-commits-and-reporting owns the format): what failed, the cause, the fix, the evidence (the passing command and its RESULT lines), the catalogue id, and any human step still needed.

The catalogue by area (each reference is a generated table: ID, symptom, cause, fix, status, platform, skill):

Area Reference Covers
build references/build-and-expo-config.md app.config.ts, variants, config plugins, prebuild, Metro, native modules
ios references/ios-xcode-and-simulator.md Xcode selection, pods, xcodebuild, the simulator
android references/android-gradle-and-emulator.md JDK and SDK, Gradle, the emulator, adb installs, signing, Android 16
release references/release-and-signing.md signing, export, store gate, App Store and Google Play uploads, processing, testers, EAS submit
deps references/dependencies-and-supply-chain.md pins, release age, held-back majors, install scripts, knip
lint references/typescript-and-lint.md TS error codes, ESLint config bugs, naming
testing references/testing-jest-and-goldens.md Jest setup, mocks, RNTL, goldens, coverage, Stryker
e2e references/e2e-maestro.md Maestro flows, named devices, driver ports
animation references/animation-skia-and-gestures.md frame callbacks, worklets, springs, Skia, frame rate, gestures
i18n references/i18n-and-rtl.md Hermes Intl, catalogs, RTL and direction switches, fonts
services references/ads-purchases-audio-privacy.md AdMob, UMP and ATT consent, purchases, audio, haptics, privacy
state references/state-persistence-navigation.md stores, SQLite, navigation, cancellation, day maths
gates references/quality-gates-and-git.md commit rules, hooks, guardrail, Claude Code hooks and settings
perf references/performance-and-accessibility.md cold start, budgets, VoiceOver, TalkBack, text scaling
parity references/visual-parity-and-screenshots.md screenshot capture and design comparison (design-visual-parity owns the full failure-message table)
skills references/agent-skills.md skills that do not load, trigger or run (skill-maintenance owns the procedure)
games references/games-optional.md the optional games plugin: determinism, real-time loops, balance
runtime references/runtime-and-dev-server.md Metro and the dev server, React red boxes, Expo Router navigation, network requests, TanStack Query, updates, crash reports, secure storage, deep links

Definition of done

  • The command that failed now passes, and the gate of its area passes.
  • The fix is at the cause: no check, limit, tolerance, golden or test was weakened, and no human stop was worked around.
  • Human steps, if any, were sent as one message and are named in the report.
  • A failure that was not in the catalogue is now an entry (or the wrong entry was corrected), with its first error line in assets/known-queries.tsv, and node ${CLAUDE_SKILL_DIR}/scripts/check-catalogue.mjs prints RESULT: PASS.
  • node ${CLAUDE_SKILL_DIR}/scripts/check-known-pitfalls.mjs . prints RESULT: PASS (it has no SKIP lines).

Anti-patterns

  • Fixing from memory. Look up first, then read the installed source; the stack is newer than most docs.
  • Retrying errSecInternalComponent, a 401/403, an agreement or a keystore password error. These are stops; send the message.
  • Raising max-params, a coverage threshold or a pixel tolerance because a check fails. That hides the defect and needs a Gate-Change: trailer and the reviewer anyway.
  • xcrun simctl erase all, adb kill-server or deleting ~/Library/Developer "to start fresh". Other sessions' devices and all evidence are gone; clean only what you created.
  • Deleting the Metro cache to fix a stale variant. It hides the missing cache key until the next build.
  • Editing a rendered reference to add a row. The next --write erases it; edit the area JSON.
  • An entry like "build failed, rebuild". Symptoms quote the error text, causes say why, fixes say what to change, and match patterns are specific (entry-match-broad fails a pattern that matches anything).
  • Declaring victory after one green run of a flaky test. Find why it flaked (time, randomness, order, a real race); jest.retryTimes is banned.

Files in this skill

File What it is Read/run when
references/diagnosing-new-failures.md The loop for unknown failures, where every log is on iOS and Android, isolation, stop rules, the entry fields, adding a pitfall rule, a worked example Workflow steps 1, 4 and 7
references/build-and-expo-config.md Generated table: build area Workflow step 3, config, prebuild and Metro failures
references/ios-xcode-and-simulator.md Generated table: ios area Workflow step 3, Xcode and simulator failures
references/android-gradle-and-emulator.md Generated table: android area Workflow step 3, Gradle, emulator and adb failures
references/release-and-signing.md Generated table: release area Workflow step 3, signing and upload failures
references/dependencies-and-supply-chain.md Generated table: deps area Workflow step 3, install, upgrade and knip failures
references/typescript-and-lint.md Generated table: lint area Workflow step 3, tsc and ESLint errors
references/testing-jest-and-goldens.md Generated table: testing area Workflow step 3, Jest failures
references/e2e-maestro.md Generated table: e2e area Workflow step 3, Maestro failures
references/animation-skia-and-gestures.md Generated table: animation area Workflow step 3, animation, canvas and gesture bugs
references/i18n-and-rtl.md Generated table: i18n area Workflow step 3, language and RTL bugs
references/ads-purchases-audio-privacy.md Generated table: services area Workflow step 3, ads, consent, purchases, audio and privacy
references/state-persistence-navigation.md Generated table: state area Workflow step 3, data, navigation and async bugs
references/quality-gates-and-git.md Generated table: gates area Workflow step 3, hook and commit failures
references/performance-and-accessibility.md Generated table: perf area Workflow step 3, perf and a11y findings
references/visual-parity-and-screenshots.md Generated table: parity area Workflow step 3, capture and design-comparison failures
references/agent-skills.md Generated table: skills area Workflow step 3, a skill misbehaves
references/games-optional.md Generated table: games area (optional plugin) Workflow step 3, game rules, loops and balance
references/runtime-and-dev-server.md Generated table: runtime area Workflow step 3, red boxes, dev-server, navigation, network and run-time faults
assets/known-failures/ The catalogue: index.json (version, reviewed date, stack, areas, skill names, banned terms) and one <area>.json per area (the one place entries are written) Workflow step 7
assets/known-queries.tsv Recorded first error lines, one <id><TAB><text> per line; check-catalogue proves each ranks its entry first Workflow step 7
scripts/find-fix.mjs Looks up error text, a log or an id; exit 1 when nothing is known Workflow step 2
scripts/check-known-pitfalls.mjs Scans the app repo for the known failures visible in files (variants, Metro, devices, versions, configs, flows, export options) Workflow step 5 and the definition of done
scripts/check-catalogue.mjs Validates the catalogue, runs the recorded queries, renders (--write) and checks the references, checks pitfall ids Workflow step 7; repo CI
scripts/lib/catalogue.mjs Catalogue loader, validator, version ranges, search ranking and renderer When changing the entry format
scripts/lib/pitfalls.mjs The pitfall rules, one per catalogue id, with layout-derived globs Workflow step 7, to add a rule
scripts/selftest.mjs Proves all three scripts against the fixtures (one planted bug per rule) and this skill's own catalogue After changing a script, a rule, an entry or a query
scripts/check-lib.mjs Shared script helper, synced from the library (do not edit here) Never by hand
assets/shared.json Declares the shared files this skill copies in When adding a shared file
tests/fixtures/ Overlay suites: a single-app tree with planted pitfalls (and silent installed-skill traps), a two-area catalogue, find-fix queries When adding a rule or a lookup case

Related skills

  • react-native-conventions-index - which skill owns a task; start there when unsure.
  • quality-gates - what each gate checks and the Gate-Change rule.
  • ios-simulator-build / android-emulator-build - running and proving a device build.
  • ios-release-testflight / android-release-play / eas-build-and-submit - the release pipelines and their stop tables.
  • dependency-management / expo-sdk-upgrade - installing, pinning and upgrading, where many held-back entries end.
  • skill-maintenance - a skill that does not load, trigger or pass the validator.
  • git-commits-and-reporting - the report and the stop message.
  • Expo's official expo-dev-client, eas-app-stores and expo-upgrade skills - Expo's own API reference for dev builds, store submission and SDK upgrades.