菜单
Diagnose and fix this project's known environment, toolchain, build, and runtime traps (bun/node shell errors, ESLint version/commit failures, TS path/CSS errors, IAP/auth 500s, FCM iOS errors). Use when a command fails, a commit is blocked, or the app errors in a way that matches a known symptom.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | troubleshoot |
| description | Diagnose and fix this project's known environment, toolchain, build, and runtime traps (bun/node shell errors, ESLint version/commit failures, TS path/CSS errors, IAP/auth 500s, FCM iOS errors). Use when a command fails, a commit is blocked, or the app errors in a way that matches a known symptom. |
Match the symptom, apply the fix. These are recurring, non-obvious issues in this repo.
Normal commands are bun install, bunx <tool>, bun run <script>.
node_modules/.bin empty → run bun install in that package
(no workspace hoisting — install per package).bun/bunx/bun run crash with
command not found: __work / maximum nested function level, your shell has a
broken version-manager shim (not a repo issue). Bypass it with the absolute binary
~/.bun/bin/bun for installs and node_modules/.bin/<tool> (tsc/eslint/jest/nest)
which don't go through the shim. Add TMPDIR=/tmp if the temp dir is full (ENOSPC).eslint-plugin-react ... contextOrFilename.getFilename is not a function
→ bunx eslint pulled ESLint 10 (unsupported). .lintstagedrc.json must use
package-local eslint via cd <pkg> && node_modules/.bin/eslint ... (ESLint 9). Don't use bunx.import/no-unresolved on @/... → eslint ran from repo root so
the resolver can't find the package tsconfig.json paths. Run with cwd = the
package (cd mobile && ...) — already how .lintstagedrc.json is set.ts(2882) on import "./styles/global.css" → covered by
declare module "*.css" in mobile/nativewind-env.d.ts; restart the TS server.bun x prisma generate; Decimal
columns are Prisma.Decimal.@CurrentUser('id') → the decorator
must honor the key (data ? user?.[data] : user); @CurrentUser('id') returns a number.JWT_SECRET ≥32, ENCRYPTION_KEY, DATABASE_URL, S3_*). See .env.example.APPLE_ROOT_CA_CERTS not set (required to
verify the JWS chain). Android webhook 401 → set GOOGLE_PUBSUB_* (fail-closed in prod).docker-compose app won't start → command must be bunx prisma migrate deploy && bun dist/src/main.js.[messaging/unregistered] ... registerDeviceForRemoteMessages → iOS must call
registerDeviceForRemoteMessages before getToken (done in messaging.ts), AND
needs the aps-environment entitlement + remote-notification background mode
(app.config.ts) + APNs key in Firebase + a real device. Rebuild: bun run prebuild && bun run ios.@CurrentUser('id') fix above.tabBarStyle.backgroundColor from theme in MainTabs.When the symptom isn't here, reproduce with the package-local binary, read the full error, and fix at the root cause (don't suppress).
Scaffold a new mobile screen and/or API call in the Expo app following this project's conventions (design-system components, navigation, TanStack Query api/core, theme, i18n). Use when adding or extending a mobile screen or backend call.
Change the Prisma schema and create an incremental migration the standard Prisma way (migrate dev for local, migrate deploy for prod), then regenerate the client and seed. Use whenever editing backend/prisma/schema.prisma or adding/altering DB tables, columns, indexes, or enums.
Scaffold a new NestJS endpoint/module/route in the backend following this project's conventions (module + controller + service + dto + constants, auth/roles, pagination, prisma, tests). Use when adding or extending a backend API.
Add a new environment variable to the backend the right way — boot-time validation, .env.example documentation, and typed access. Use when introducing any new backend config/secret/flag.
Audit the project against its production/deploy checklist — required secrets, migrations, store/push config, security toggles, and the verification gate. Use before a release, a deploy, or when asked if the app is production-ready.
Write unit tests following this repo's conventions for backend (NestJS, ts-jest, *.spec.ts) and mobile (jest-expo, *.test.ts, RNFB/native mocking). Use when adding test coverage for services, guards, pipes, hooks, stores, or utilities.