Skill: diagnose

On load: Read ../../.claude-plugin/plugin.json from this skill's base directory. Display diagnose v{version} before proceeding.

Diagnose React Native errors by matching against known patterns, searching official docs, and inspecting project configuration.

IMPORTANT: Build logs and simulator screenshots can be enormous.
Always process them in a subagent to protect main context.

---

Dependencies

Skill / Resource	Why
ios-sim	capture.sh view captures red screen error text when the user says "there's an error on screen"; also used in optional post-fix verification
_shared (metro.sh)	Step 0 — Metro health check, bundle validation, stack symbolication
refs/react-native-docs	Step 3 — doc search for error context and fix guidance

---

Error Pattern Database

Read ${CLAUDE_SKILL_DIR}/references/error-patterns.md for the full pattern catalog (24 patterns covering Metro, build, runtime, and dependency errors).

Step 0 uses ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh for live Metro health checks before deep diagnosis.

Docs Location

${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/

---

Routing Table

Error Category	Source	Workflow
User pastes error text	Direct input	pattern-match → docs search
Error visible on simulator	Simulator screen	capture → pattern-match → docs search
Build log failure	Xcode / Gradle output	log-parse (subagent if large) → pattern-match
Config / dependency issue	Project files	config-check → pattern-match
Metro / environment issue	Any	Step 0 (metro health) → pattern-match if bundle error
Unknown / unclear	Any	full-diagnosis (all steps)

---

Workflow

Step 0: Environment + Metro Health Check

Before deep diagnosis, get the environment summary and check health.

0. Get environment context (run once, reuse throughout):

   ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh env
   

   Returns JSON with metro, expo, newArch, entry, platform. Use this to inform diagnosis — Expo and vanilla RN have different error patterns.

1. Check if Metro is running:

   ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh status
   

   • If Metro is not running: note this as a potential root cause. For Expo projects, suggest npx expo start. For vanilla RN, suggest npx react-native start.
   • If Metro is running: proceed to bundle check.

2. Check if the JS bundle compiles:

   ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh bundle-check --platform ios
   

   • If exit code is non-zero (500 response): capture the error body for pattern matching in Step 2.
   • If bundle builds successfully: Metro environment is healthy, proceed.

3. Symbolicate raw stack traces (if provided): If the user provides a raw stack trace, pipe the stack trace JSON to symbolicate before pattern matching:

   echo '<stack-trace-json>' | ${CLAUDE_SKILL_DIR}/../_shared/scripts/metro.sh symbolicate
   

   Use the symbolicated output for pattern matching instead of the raw trace.

If Step 0 finds Metro is down or the bundle fails, this is often the root cause.
Report it immediately rather than proceeding through all steps.

Step 1: Obtain Error Text

If user provides error text: Parse it directly — extract the core error message, stripping ANSI codes and noisy stack frames.

If user says "there's an error on screen": Dispatch ios-sim subagent to capture it:

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "diagnose: capture error from simulator"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../ios-sim/scripts/capture.sh view
       This outputs a file path to a compressed JPEG.
    2. Read that file path with the Read tool to see the image.
    3. Extract all error text visible on screen:
       - Red screen error title and message
       - Stack trace lines (file names and line numbers)
       - Any component names mentioned
    4. Return the extracted error text only. Be precise — include exact
       error messages and module names. No image descriptions needed.

Step 2: Match Against Known Patterns

Read ${CLAUDE_SKILL_DIR}/references/error-patterns.md and match the error text against the patterns. Check for substring matches on the Match fields.

Step 3: Search Official Docs

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "diagnose: search docs for error context"
  prompt: |
    Search React Native docs for information related to this error.

    ERROR: [insert extracted error text]

    1. Grep ${CLAUDE_SKILL_DIR}/../../refs/react-native-docs/ for key
       terms from the error (component names, API names, error codes).
    2. Read any matching files (max 3 most relevant).
    3. Return:
       - Which doc files mention this topic
       - Relevant API usage notes or caveats
       - Any documented workarounds or migration notes
    Be concise. Quote doc filenames for citation.

Step 4: Check Project Config (if build/dependency error)

For build and dependency errors, read the user's project files directly:

File	Check For
package.json	RN version, dependency versions, scripts
ios/Podfile	Hermes flag, Flipper, platform version, use_frameworks
android/gradle.properties	newArchEnabled, hermesEnabled, JVM args
android/app/build.gradle	compileSdk, targetSdk, minSdk, dependencies
metro.config.js	watchFolders, transformer, resolver config
babel.config.js	Presets, plugins (reanimated, module-resolver)

Only read files relevant to the error category. Use Glob to find them:

Glob pattern: {package.json,ios/Podfile,android/gradle.properties,android/app/build.gradle,metro.config.*,babel.config.*}

Step 5: Process Large Build Logs (if needed)

If the user pastes or references a large build log (>100 lines), dispatch a subagent:

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "diagnose: parse build log"
  prompt: |
    Parse this build log and extract the root error.

    BUILD LOG:
    [insert log content]

    1. Skip all successful build steps and warnings.
    2. Find the FIRST fatal error or failure line.
    3. Extract: error message, file path, line number if present.
    4. Note any "required by" or dependency chain info.
    5. Return just the essential error info (under 10 lines).

---

Response Format

After diagnosis, return to the user:

1. Error: One-line summary of what went wrong
2. Root Cause: Why it happened (1-2 sentences)
3. Fix: Concrete commands or code changes to resolve it
4. Doc Reference: Filename from official docs if relevant
5. Verify: How to confirm the fix worked (rebuild command, or offer to check simulator)

---

Optional: Verify Fix via Simulator

After the user applies the fix, offer to verify by dispatching ios-sim:

Dispatch Agent:
  subagent_type: general-purpose
  model: haiku
  description: "diagnose: verify fix on simulator"
  prompt: |
    1. Run: ${CLAUDE_SKILL_DIR}/../ios-sim/scripts/capture.sh view
    2. Read the output file path to see the screenshot.
    3. Check if the error is still visible or if the app loaded successfully.
    4. Return: "FIXED — [what's now on screen]" or "STILL FAILING — [error text]"

---

Context Efficiency

Item	Size	In Main Context?
Metro health check	~50 chars	YES (small output)
Error pattern DB	~4 KB	YES (read once)
Simulator screenshot	~100-300 KB	NEVER — subagent
Build log parsing	~1-50 KB	Subagent if >100 lines
Doc search results	~2-10 KB	Subagent
Project config files	~1-3 KB each	YES (targeted reads)
Final diagnosis	~200-500 chars	YES