troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- troubleshooting-playbook
- description
- Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
02 资源文件 350
- 资产文件assets/known-failures.json346.5 KB
- 资产文件assets/shared.json73 B
- 参考文档references/ads-purchases-privacy.md25.3 KB
- 参考文档references/android-build-and-release.md24.5 KB
- 参考文档references/build-and-simulator.md20.2 KB
- 参考文档references/claude-code-and-skills.md10.5 KB
- 参考文档references/dependencies-and-supply-chain.md16.7 KB
- 参考文档references/diagnosing-new-failures.md8.1 KB
- 参考文档references/i18n-and-rtl.md11.3 KB
- 参考文档references/open-risks.md10.5 KB
- 参考文档references/performance-and-accessibility.md4.8 KB
- 参考文档references/quality-gates-and-git.md11.5 KB
- 参考文档references/release-and-signing.md12.8 KB
- 参考文档references/rendering-and-game-loop.md11.9 KB
- 参考文档references/state-persistence-navigation.md8.1 KB
- 参考文档references/testing-and-e2e.md35.1 KB
- 参考文档references/typescript-and-lint.md17.6 KB
- 参考文档references/visual-parity.md21.4 KB
- 脚本scripts/check-catalogue.mjs3.8 KB
- 脚本scripts/check-known-pitfalls.mjs3.6 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/find-fix.mjs5.2 KB
- 脚本scripts/lib/catalogue.mjs6.5 KB
- 脚本scripts/lib/pitfalls.mjs25.2 KB
- 脚本scripts/selftest.mjs2.8 KB
- 参考文档tests/fixtures/check-catalogue/bad-entries/EXPECT.txt195 B
- 参考文档tests/fixtures/check-catalogue/bad-entries/known-failures.json2.3 KB
- 参考文档tests/fixtures/check-catalogue/bad-shape/EXPECT.txt55 B
- 参考文档tests/fixtures/check-catalogue/bad-shape/known-failures.json51 B
- 参考文档tests/fixtures/check-catalogue/bad-stale-references/EXPECT.txt98 B
- 参考文档tests/fixtures/check-catalogue/bad-stale-references/known-failures.json1.1 KB
- 参考文档tests/fixtures/check-catalogue/bad-stale-references/references/build.md25 B
- 参考文档tests/fixtures/check-catalogue/good/known-failures.json1.1 KB
- 参考文档tests/fixtures/check-catalogue/good/references/build.md804 B
- 参考文档tests/fixtures/check-catalogue/good/references/release.md771 B
- 其他tests/fixtures/check-known-pitfalls/bad-android-tracked/apps/line-siege/android/app/build.gradle139 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android-tracked/EXPECT.txt93 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android-tracked/GIT-ADD.txt54 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android-tracked/package.json99 B
- 其他tests/fixtures/check-known-pitfalls/bad-android/.gitignore40 B
- 脚本tests/fixtures/check-known-pitfalls/bad-android/apps/line-siege/app.config.ts308 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android/apps/line-siege/e2e/offline/01-airplane.yaml367 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android/apps/line-siege/e2e/offline/02-unguarded.yaml220 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android/EXPECT.txt352 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-android/package.json199 B
- 脚本tests/fixtures/check-known-pitfalls/bad-android/packages/tooling/src/android/toolchain.ts282 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/app.config.ts308 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/e2e/home/01-offline.yaml144 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/index.ts169 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/ios/Pods/Local/should-be-skipped.ts56 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/metro.config.js330 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/apps/line-siege/package.json267 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/babel.config.js112 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/eslint.config.mjs381 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/EXPECT.txt710 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/jest.config.js223 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/knip.json72 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/package.json410 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/game-kit/src/geom/unit-shapes.ts238 B
- 其他tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/app/startup-splash.tsx360 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/app/test-only.ts248 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/config/shell-plugins.ts276 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/config/with-shell.ts284 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/game-host/board-scene.test.ts445 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/game-host/board-scene.ts388 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/i18n/locale-data.ts335 B
- 其他tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/ui/pack-stars.tsx476 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/shell/src/ui/pulse.ts323 B
- 其他tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/config/export-options-store.plist343 B
- 其他tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/config/export-options-test.plist406 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/src/art/render-art.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/src/asc/asc-client.ts162 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/src/e2e/run-e2e-ios.ts174 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/src/ios/toolchain.ts298 B
- 脚本tests/fixtures/check-known-pitfalls/bad-configs/packages/tooling/src/quality/check-commit-message.ts305 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-configs/quality-gates.json122 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/app.config.ts308 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/e2e/home/01-offline.yaml137 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/index.ts169 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/ios/Pods/Local/should-be-skipped.ts56 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/metro.config.js330 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-dependencies/apps/line-siege/package.json433 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/eslint.config.mjs405 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-dependencies/EXPECT.txt273 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/jest.config.js529 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-dependencies/package.json410 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/game-kit/src/geom/unit-shapes.ts238 B
- 其他tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/app/startup-splash.tsx360 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/app/test-only.ts248 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/config/with-shell.ts329 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/game-host/board-scene.test.ts445 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/game-host/board-scene.ts388 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/i18n/locale-data.ts335 B
- 其他tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/ui/pack-stars.tsx476 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/shell/src/ui/pulse.ts323 B
- 其他tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/config/export-options-store.plist406 B
- 其他tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/config/export-options-test.plist406 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/src/art/render-art.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/src/asc/asc-client.ts238 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/src/e2e/run-e2e-ios.ts203 B
- 脚本tests/fixtures/check-known-pitfalls/bad-dependencies/packages/tooling/src/ios/toolchain.ts505 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-dependencies/quality-gates.json180 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/app.config.ts308 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/e2e/home/01-offline.yaml137 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/index.ts169 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/ios/Pods/Local/should-be-skipped.ts56 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/metro.config.js330 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-runtime-code/apps/line-siege/package.json267 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/babel.config.js112 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/eslint.config.mjs405 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-runtime-code/EXPECT.txt911 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/jest.config.js529 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-runtime-code/package.json410 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/game-kit/src/geom/unit-shapes.ts204 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/app/ask-tracking-early.ts281 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/app/create-shell-parts.ts297 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/app/startup-splash.tsx360 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/app/test-only.ts248 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/app/use-reduce-motion-setting.test.ts631 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/config/with-shell.ts329 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/game-host/board-scene.test.ts445 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/game-host/board-scene.ts388 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/i18n/direction.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/i18n/locale-data.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/screens/daily/next-in.ts174 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/services/save/sqlite-save-store.ts388 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/stats/format-day.ts183 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/flag-bob.tsx444 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/glow-ring.tsx472 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/hint-pulse.tsx504 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/pack-stars.tsx267 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/pulse.ts278 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/shell/src/ui/wiggle-badge.tsx595 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/config/export-options-store.plist406 B
- 其他tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/config/export-options-test.plist406 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/src/art/render-art.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/src/asc/asc-client.ts238 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/src/e2e/run-e2e-ios.ts203 B
- 脚本tests/fixtures/check-known-pitfalls/bad-runtime-code/packages/tooling/src/ios/toolchain.ts505 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-runtime-code/quality-gates.json180 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/app.config.ts178 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/e2e/home/01-offline.yaml137 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/index.ts177 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/ios/Pods/Local/should-be-skipped.ts56 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/metro.config.js141 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-variants/apps/line-siege/package.json267 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/babel.config.js112 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/eslint.config.mjs405 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-variants/EXPECT.txt230 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/jest.config.js529 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-variants/package.json410 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/game-kit/src/geom/unit-shapes.ts238 B
- 其他tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/app/startup-splash.tsx360 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/app/test-only.ts248 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/config/with-shell.ts329 B
- 其他tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/debug/debug-menu.tsx174 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/game-host/board-scene.test.ts445 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/game-host/board-scene.ts388 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/i18n/locale-data.ts335 B
- 其他tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/ui/pack-stars.tsx476 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/shell/src/ui/pulse.ts323 B
- 其他tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/config/export-options-store.plist406 B
- 其他tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/config/export-options-test.plist406 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/src/art/render-art.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/src/asc/asc-client.ts238 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/src/e2e/run-e2e-ios.ts203 B
- 脚本tests/fixtures/check-known-pitfalls/bad-variants/packages/tooling/src/ios/toolchain.ts505 B
- 参考文档tests/fixtures/check-known-pitfalls/bad-variants/quality-gates.json180 B
- 其他tests/fixtures/check-known-pitfalls/good/.gitignore56 B
- 脚本tests/fixtures/check-known-pitfalls/good/apps/line-siege/app.config.ts308 B
- 参考文档tests/fixtures/check-known-pitfalls/good/apps/line-siege/e2e/home/01-offline.yaml137 B
- 参考文档tests/fixtures/check-known-pitfalls/good/apps/line-siege/e2e/offline/01-airplane.yaml470 B
- 参考文档tests/fixtures/check-known-pitfalls/good/apps/line-siege/e2e/subflows/airplane-off.yaml106 B
- 参考文档tests/fixtures/check-known-pitfalls/good/apps/line-siege/e2e/subflows/airplane-steps.yaml572 B
- 脚本tests/fixtures/check-known-pitfalls/good/apps/line-siege/index.ts169 B
- 脚本tests/fixtures/check-known-pitfalls/good/apps/line-siege/ios/Pods/Local/should-be-skipped.ts56 B
- 脚本tests/fixtures/check-known-pitfalls/good/apps/line-siege/metro.config.js330 B
- 参考文档tests/fixtures/check-known-pitfalls/good/apps/line-siege/package.json267 B
- 脚本tests/fixtures/check-known-pitfalls/good/babel.config.js112 B
- 脚本tests/fixtures/check-known-pitfalls/good/eslint.config.mjs405 B
- 脚本tests/fixtures/check-known-pitfalls/good/jest.config.js759 B
- 参考文档tests/fixtures/check-known-pitfalls/good/knip.json83 B
- 参考文档tests/fixtures/check-known-pitfalls/good/package.json410 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/game-kit/src/geom/unit-shapes.ts238 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/app/create-shell-parts.ts428 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/shell/src/app/startup-splash.tsx360 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/app/test-only.ts248 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/config/shell-plugins.ts433 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/config/with-shell.ts329 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/game-host/board-scene.test.ts445 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/game-host/board-scene.ts388 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/shell/src/game-host/coach-hand-layer.tsx790 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/i18n/locale-data.ts335 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/screens/daily/use-next-day-countdown.ts332 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/services/consent/admob-consent-adapter.ts432 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/services/save/sqlite-save-store.ts400 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/shell/src/ui/flag-bob.tsx523 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/shell/src/ui/pack-stars.tsx476 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/shell/src/ui/pulse.ts323 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/tooling/config/export-options-store.plist406 B
- 其他tests/fixtures/check-known-pitfalls/good/packages/tooling/config/export-options-test.plist406 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/android/toolchain.ts268 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/art/render-art.ts164 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/asc/asc-client.ts238 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/e2e/run-e2e-ios.ts203 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/ios/toolchain.ts505 B
- 脚本tests/fixtures/check-known-pitfalls/good/packages/tooling/src/quality/check-commit-message.ts334 B
- 参考文档tests/fixtures/check-known-pitfalls/good/quality-gates.json180 B
- 参考文档tests/fixtures/find-fix-text/bad-unknown-text/EXPECT.txt38 B
- 参考文档tests/fixtures/find-fix-text/bad-unknown-text/queries.txt110 B
- 参考文档tests/fixtures/find-fix-text/good/queries.txt10.7 KB
- 参考文档tests/fixtures/find-fix-text/pass-top-android-adb-more-than-one-device/EXPECT.txt41 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-adb-more-than-one-device/queries.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-play-auth/EXPECT.txt26 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-play-auth/queries.txt177 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-play-store-image/EXPECT.txt33 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-play-store-image/queries.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-version-code-used/EXPECT.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-android-version-code-used/queries.txt120 B
- 参考文档tests/fixtures/find-fix-text/pass-top-engine-board-freeze-rewarded-continue/EXPECT.txt46 B
- 参考文档tests/fixtures/find-fix-text/pass-top-engine-board-freeze-rewarded-continue/queries.txt116 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-perf-baseline-gated/EXPECT.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-perf-baseline-gated/queries.txt126 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-release-script-missing/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-release-script-missing/queries.txt78 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-report-outcome-limits/EXPECT.txt36 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-report-outcome-limits/queries.txt90 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-test-edits-directed-history/EXPECT.txt42 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-test-edits-directed-history/queries.txt167 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-wiring-pending-targets/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-gates-wiring-pending-targets/queries.txt137 B
- 参考文档tests/fixtures/find-fix-text/pass-top-i18n-debug-text-translated/EXPECT.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-i18n-debug-text-translated/queries.txt93 B
- 参考文档tests/fixtures/find-fix-text/pass-top-i18n-unreviewed-texts/EXPECT.txt30 B
- 参考文档tests/fixtures/find-fix-text/pass-top-i18n-unreviewed-texts/queries.txt83 B
- 参考文档tests/fixtures/find-fix-text/pass-top-lint-jest-image-snapshot-types/EXPECT.txt39 B
- 参考文档tests/fixtures/find-fix-text/pass-top-lint-jest-image-snapshot-types/queries.txt124 B
- 参考文档tests/fixtures/find-fix-text/pass-top-lint-step7-missing-core-files/EXPECT.txt38 B
- 参考文档tests/fixtures/find-fix-text/pass-top-lint-step7-missing-core-files/queries.txt116 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-family-sharing/EXPECT.txt28 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-family-sharing/queries.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-home-opens-daily/EXPECT.txt30 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-home-opens-daily/queries.txt48 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-owner-personal-checks-2/EXPECT.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-owner-personal-checks-2/queries.txt17 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-owner-personal-checks/EXPECT.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-owner-personal-checks/queries.txt51 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-parity-hint-key-no-hints/EXPECT.txt38 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-parity-hint-key-no-hints/queries.txt81 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-parity-score-value-persian-clip/EXPECT.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-parity-score-value-persian-clip/queries.txt111 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-price-point/EXPECT.txt25 B
- 参考文档tests/fixtures/find-fix-text/pass-top-open-price-point/queries.txt30 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-balanced-wrap-stalls/EXPECT.txt36 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-balanced-wrap-stalls/queries.txt28 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-dialog-modal-hides-scrim-2/EXPECT.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-dialog-modal-hides-scrim-2/queries.txt80 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-dialog-modal-hides-scrim/EXPECT.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-dialog-modal-hides-scrim/queries.txt38 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline-2/EXPECT.txt47 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline-2/queries.txt28 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline-3/EXPECT.txt47 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline-3/queries.txt21 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline/EXPECT.txt47 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-display-balance-digits-baseline/queries.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hierarchy-other-simulator-2/EXPECT.txt41 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hierarchy-other-simulator-2/queries.txt72 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hierarchy-other-simulator/EXPECT.txt41 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hierarchy-other-simulator/queries.txt43 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hold-fill-short/EXPECT.txt31 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-hold-fill-short/queries.txt22 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-persian-overflow-high/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-persian-overflow-high/queries.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-quiet-underline/EXPECT.txt31 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-quiet-underline/queries.txt43 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-ads-switch-off/EXPECT.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-ads-switch-off/queries.txt215 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-badge-high/EXPECT.txt30 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-badge-high/queries.txt160 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-persian-digits/EXPECT.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-s15-persian-digits/queries.txt167 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-signoff-date-utc/EXPECT.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-signoff-date-utc/queries.txt80 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-sliver-counts-missing/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-sliver-counts-missing/queries.txt36 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-text-ink-neighbour/EXPECT.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-parity-text-ink-neighbour/queries.txt34 B
- 参考文档tests/fixtures/find-fix-text/pass-top-perf-hold-label-contrast/EXPECT.txt33 B
- 参考文档tests/fixtures/find-fix-text/pass-top-perf-hold-label-contrast/queries.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-2/EXPECT.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-2/queries.txt56 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-3/EXPECT.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-3/queries.txt28 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-4/EXPECT.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids-4/queries.txt192 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids/EXPECT.txt32 B
- 参考文档tests/fixtures/find-fix-text/pass-top-release-placeholder-ids/queries.txt104 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-alert-over-form/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-alert-over-form/queries.txt75 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-crash-no-usage-string/EXPECT.txt43 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-crash-no-usage-string/queries.txt247 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt-never-shows-2/EXPECT.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt-never-shows-2/queries.txt61 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt-never-shows/EXPECT.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt-never-shows/queries.txt25 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt/EXPECT.txt28 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-att-prompt/queries.txt47 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-eea-form-never-shows/EXPECT.txt38 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-eea-form-never-shows/queries.txt79 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-endless-result-stranded/EXPECT.txt41 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-endless-result-stranded/queries.txt56 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-gma-tracking-label/EXPECT.txt36 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-gma-tracking-label/queries.txt82 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-sample-idfa-explainer/EXPECT.txt39 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-sample-idfa-explainer/queries.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-ui-feedback-toggle-not-due/EXPECT.txt44 B
- 参考文档tests/fixtures/find-fix-text/pass-top-services-ui-feedback-toggle-not-due/queries.txt124 B
- 参考文档tests/fixtures/find-fix-text/pass-top-skills-bash-every-call-exits-1/EXPECT.txt39 B
- 参考文档tests/fixtures/find-fix-text/pass-top-skills-bash-every-call-exits-1/queries.txt39 B
- 参考文档tests/fixtures/find-fix-text/pass-top-skills-parity-selftest-tooling-option/EXPECT.txt46 B
- 参考文档tests/fixtures/find-fix-text/pass-top-skills-parity-selftest-tooling-option/queries.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-state-shell-app-test-at-step-7/EXPECT.txt39 B
- 参考文档tests/fixtures/find-fix-text/pass-top-state-shell-app-test-at-step-7/queries.txt104 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-balance-report-stale-2/EXPECT.txt37 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-balance-report-stale-2/queries.txt126 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-coverage-untested-templates-2/EXPECT.txt44 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-coverage-untested-templates-2/queries.txt69 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-debug-perf-summary-stale/EXPECT.txt41 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-debug-perf-summary-stale/queries.txt76 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-debug-setup-banner-open/EXPECT.txt40 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-debug-setup-banner-open/queries.txt45 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-maestro-hierarchy-500-hang/EXPECT.txt43 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-maestro-hierarchy-500-hang/queries.txt109 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-maestro-port-clash-parity-sim/EXPECT.txt46 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-maestro-port-clash-parity-sim/queries.txt90 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-network-sampler-other-simulator/EXPECT.txt48 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-network-sampler-other-simulator/queries.txt64 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-render-with-shell-no-shell-context-2/EXPECT.txt51 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-render-with-shell-no-shell-context-2/queries.txt205 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-run-e2e-help-stack/EXPECT.txt35 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-run-e2e-help-stack/queries.txt71 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-save-benchmark-writes/EXPECT.txt38 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-save-benchmark-writes/queries.txt129 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-step6-tests-need-render-with-shell/EXPECT.txt51 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-step6-tests-need-render-with-shell/queries.txt116 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-storekit-harness-busy-mac/EXPECT.txt42 B
- 参考文档tests/fixtures/find-fix-text/pass-top-testing-storekit-harness-busy-mac/queries.txt138 B
- 其他tests/fixtures/find-fix/bad-unknown-error/build.log90 B
- 参考文档tests/fixtures/find-fix/bad-unknown-error/EXPECT.txt41 B
- 其他tests/fixtures/find-fix/good/build.log188 B
03 SKILL.md 正文
Troubleshooting playbook
Turns an error into a proven fix fast: look the failure up in the catalogue of every failure solved so far (over 300 entries, each with symptom, cause, fix, status and the skill that owns the procedure), apply the fix at its cause, prove it with the command that failed, and record anything new so the next session finds it in seconds.
Rules that must hold
- Look it up before you diagnose. Run
find-fix.mjswith 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 on restart) and were expensive to find; guessing repeats that cost. - 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. - Rows marked owner are stops. Keychain, agreements, 401/403 (App Store Connect or the Android Publisher API), a missing app record, the Xcode licence,
sudo, consoles and product decisions: send the owner one message (the step, the exact error line, the one action needed) and wait. Retrying can lock the account or burn build numbers; the decisions are the owner's. The owner's personal checks (the review of fa and ckb texts, the play-test, listening to the sound previews) are not stops: list them under "Owner steps (not blocking)" and keep working (open-owner-personal-checks). - When an entry names a skill, load that skill for the fix. The catalogue gives the diagnosis; the owning skill has the full procedure, templates and checks that prove the fix.
- 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
check:fast,verify, the simulator build or the release gate, is. - Treat
openentries as the current decision, not as bugs. Their fix is the agreed fallback. Tell the owner when you hit one; never settle it silently. - Record every newly solved failure in
assets/known-failures.json, never in the rendered references. Then re-render withcheck-catalogue.mjs --write. When the cause is visible in repo files, add a rule toscripts/lib/pitfalls.mjswith a planted-bug fixture, so the checker catches it before it happens. - 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.
- Never destroy evidence or other tasks' state to "start clean". No
simctl erase allorshutdown all, noxcode-select, no wiping caches ornode_modulesbefore the cause is known, nevernpm installthrough a symlinkednode_modules.
Workflow
- Capture the first error line (not the last) and the command that produced it. The logs are listed in references/diagnosing-new-failures.md ("Where the evidence is").
- Look it up:
node ${CLAUDE_SKILL_DIR}/scripts/find-fix.mjs --text "<first error line>". Also try two or three plain words for what you see ("banner never appears"),--log <file>for a whole log (error patterns only), or--id <id>for an id another checker printed. EveryMATCHprints the cause, the fix, the status and the owning skill. - Act on the match. Marked
stop and ask the owner: 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 the area is in its reference (below); read it when the match is close but not exact. - No match, or the fix did not work: read references/diagnosing-new-failures.md and follow its loop: reproduce cleanly, change one thing at a time, suspect the newest change first, make a minimal repro in a scratch copy for library bugs.
- Scan for known pitfalls before a first simulator or emulator build, a release, a dependency or SDK bump, a new game, and whenever failures repeat:
node ${CLAUDE_SKILL_DIR}/scripts/check-known-pitfalls.mjs .from the repo root. EachFAILline names the file, the catalogue id, the fix and the cause; fix and rerun untilRESULT: PASS. - Verify: rerun the failing command, then the area's gate (
npm run -s check:fast,npm run verify,npm run build:ios:sim -- --app <game>, or the release gate). - Record: add or correct the entry in
assets/known-failures.json(field rules in the diagnosing reference), runnode ${CLAUDE_SKILL_DIR}/scripts/check-catalogue.mjs --write, thencheck-catalogue.mjswithout flags. Add the exact first error line as one line oftests/fixtures/find-fix-text/good/queries.txt, so the self-test provesfind-fix.mjsfinds it. If you added a pitfall rule, add its planted bug to atests/fixtures/check-known-pitfalls/bad-*folder. Then runnode ${CLAUDE_SKILL_DIR}/scripts/selftest.mjs. - Report in plain words: what failed, the cause, the fix, the evidence (the passing command and the
RESULTlines), the catalogue id, and any owner action still needed.
The catalogue by area (each reference is a generated table: ID, symptom, cause, fix, status, skill):
| Area | Reference | Covers |
|---|---|---|
| build | references/build-and-simulator.md | Xcode selection, app.config.ts, variants, prebuild, xcodebuild, simulator, screenshots |
| release | references/release-and-signing.md | signing, keychain, export, store gate, upload, processing, App Store Connect |
| deps | references/dependencies-and-supply-chain.md | pins, release age, install scripts, held-back majors, banned packages, knip |
| lint | references/typescript-and-lint.md | TS error codes, ESLint config bugs, naming, imports |
| testing | references/testing-and-e2e.md | Jest setup, mocks, RNTL, goldens, coverage, Stryker, Maestro |
| engine | references/rendering-and-game-loop.md | frame clock, determinism, worklets, Skia, Reanimated, gestures, physics |
| i18n | references/i18n-and-rtl.md | Hermes Intl, catalogs, RTL layout, direction reload, fonts |
| services | references/ads-purchases-privacy.md | AdMob, consent, StoreKit, audio, haptics, privacy manifests |
| state | references/state-persistence-navigation.md | save file, SQLite, stores, navigator, statistics, daily |
| parity | references/visual-parity.md | design capture, app capture, comparison traps |
| gates | references/quality-gates-and-git.md | commit rules, hooks, guardrail, Claude Code settings |
| perf | references/performance-and-accessibility.md | cold start, budgets, contrast, text scaling |
| skills | references/claude-code-and-skills.md | skills that do not load, trigger or run |
| open | references/open-risks.md | unverified behaviour and owner decisions, with the fallback until settled |
| android | references/android-build-and-release.md | JDK, SDK, NDK and Gradle, the variant inside Gradle, emulator and adb, upload-key signing, the store-AAB gate, the Play API stops, the Android gaps of the iOS-first Shell |
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 owner stop was worked around.
- [ ] Owner actions, 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) and
node ${CLAUDE_SKILL_DIR}/scripts/check-catalogue.mjsprintsRESULT: PASS. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-known-pitfalls.mjs .printsRESULT: PASS
Anti-patterns
- Fixing from memory. Training data uses APIs this stack removed or changed (
runOnJS,.value,Skia.Path.Make(), RNGH builder callbacks, Jest 30, ESLint 10). Look up first, then read the installed source. - Retrying
errSecInternalComponent, a 401 or an agreement error. These are stops; send the message. - Raising
max-paramsor a pixel tolerance because a check fails. That hides the defect and needs aGate-Change:trailer and the owner anyway. xcrun simctl erase allor deleting~/Library/Developer"to start fresh". Other tasks' simulators and all evidence are gone; clean onlyapps/<game>/buildand your owne07-*simulator.- Editing
references/build-and-simulator.mdto add a row. The next--writeerases it; edit the 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.
- Declaring victory after one green run of a flaky test. Find why it flaked (time, randomness, order, a real race);
jest.retryTimesis 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, isolation, stop rules, the entry fields and a worked example | Workflow steps 1, 4 and 7 |
| references/build-and-simulator.md | Generated table: build area | Workflow step 3, build failures |
| references/release-and-signing.md | Generated table: release area | Workflow step 3, release failures |
| references/dependencies-and-supply-chain.md | Generated table: deps area | Workflow step 3, install and upgrade failures |
| references/typescript-and-lint.md | Generated table: lint area | Workflow step 3, tsc and ESLint errors |
| references/testing-and-e2e.md | Generated table: testing area | Workflow step 3, test failures |
| references/rendering-and-game-loop.md | Generated table: engine area | Workflow step 3, board, animation and gesture bugs |
| references/i18n-and-rtl.md | Generated table: i18n area | Workflow step 3, language and RTL bugs |
| references/ads-purchases-privacy.md | Generated table: services area | Workflow step 3, ads, IAP, audio and privacy |
| references/state-persistence-navigation.md | Generated table: state area | Workflow step 3, save and navigation bugs |
| references/visual-parity.md | Generated table: parity area | Workflow step 3, design comparison problems |
| 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/claude-code-and-skills.md | Generated table: skills area | Workflow step 3, a skill misbehaves |
| references/open-risks.md | Generated table: open risks and owner decisions | Workflow step 3, and before telling the owner about an open item |
| references/android-build-and-release.md | Generated table: android area | Workflow step 3, Android build, emulator and Google Play failures |
assets/known-failures.json |
The catalogue: 15 areas and every entry (the one place entries are written) | 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, banned packages, clock, selectors, configs, flows, export options, a committed android/, the emulator image, Gradle without the variant) | Workflow step 5 and the definition of done |
scripts/check-catalogue.mjs |
Validates the catalogue, renders (--write) and checks the area references, checks pitfall ids |
Workflow step 7 |
scripts/lib/catalogue.mjs |
Catalogue loader, validator and renderer | When changing the entry format |
scripts/lib/pitfalls.mjs |
The pitfall rules, one per catalogue id | Workflow step 7, to add a rule |
scripts/selftest.mjs |
Proves all three scripts pass good fixtures and catch every planted bug, and that find-fix.mjs finds each exact error text in tests/fixtures/find-fix-text/good/queries.txt |
After changing a script, a rule or an entry's match patterns |
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/ |
Good and planted-bad repos, catalogues, logs and error-text queries for the self-test | When adding a rule, or an entry whose text must be found |
Related skills
ios-simulator-build- running and proving the Release simulator build.ios-release-testflight- the release pipeline and its own stop table.quality-gates- what each gate checks and the Gate-Change rule.dependency-management- installing, pinning and upgrading packages.expo-sdk-upgrade- moving SDK or Xcode, where many held-back entries end.skill-maintenance- a skill that does not load, trigger or pass the validator.git-commits-and-reporting- the owner report and stop messages.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).
toybox-screens
Builds Pocket Arcade screens S1-S15 to their Toybox specs: layout, spacing, the exact screen-map testIDs, copy keys, every state, banner slots, reference images. Use when building or changing a screen, overlay or dialog. Not for components (toybox-components) or pixel compare (toybox-visual-parity).