react-native-upgrader

name	react-native-upgrader
description	Use when upgrading a React Native project to a newer version, when the user mentions React Native upgrade, version bump, migration between RN versions, outdated React Native, or rn-diff-purge

React Native Upgrade Assistant

Orchestrates React Native upgrades in two phases: Analysis then optional Execution. Uses subagents for token-heavy work (release notes, diff parsing).

When to Use

• User asks to upgrade React Native to a specific version
• User asks to analyze what an RN upgrade involves
• User mentions react-native upgrade or version migration

Quick Reference

Step	Phase	Who	What
1	Analysis	You	Detect current & target versions from package.json
2	Analysis	You	Generate & validate diff URL (rn-diff-purge)
3	Analysis	Subagent	Fetch release notes for all intermediate versions
4	Analysis	You	Present summary + complexity assessment, ask user to proceed
5	Execution	Subagent	Apply diff (deps → config → Android → iOS), run cleanup
6	Execution	You	Summarize results, list manual steps & verification

When NOT to Use

• Expo managed workflow — use expo upgrade or npx expo install instead
• Upgrading a single dependency (e.g., just react-navigation) — that's a normal package update, not an RN upgrade
• Brownfield / hybrid apps — this skill assumes a standard RN template structure; heavily customized native projects need manual upgrade planning
• Downgrading — this skill only handles upgrading to a newer version

Phase 1: Analysis (Always Run)

Step 1: Detect Versions

• Read current RN version from project package.json (dependencies["react-native"])
• Strip any semver range prefix (^, ~, >=, etc.) to get the bare version (e.g., ^0.73.6 → 0.73.6)
• If no target version provided, ask the user
• Validate both are semver format (e.g., 0.79.2, 1.0.0)
• Confirm target is newer than current

Step 2: Generate and Validate Diff URL

The raw diff URL format (this is NOT the web UI):

https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/{CURRENT}..{TARGET}.diff

Example: https://raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/0.73.6..0.75.4.diff

Validate the diff exists by fetching the URL:

digraph diff_validation {
    "Fetch diff URL" [shape=box];
    "Got 200?" [shape=diamond];
    "Proceed to Step 3" [shape=box, style=filled, fillcolor=lightgreen];
    "Check release exists" [shape=box];
    "Release exists?" [shape=diamond];
    "Tell user: version invalid.\nAsk for valid target." [shape=box, style=filled, fillcolor=lightyellow];
    "Tell user: diff unavailable.\nLink to rn-diff-purge.\nAsk for closest match." [shape=box, style=filled, fillcolor=lightyellow];

    "Fetch diff URL" -> "Got 200?";
    "Got 200?" -> "Proceed to Step 3" [label="yes"];
    "Got 200?" -> "Check release exists" [label="404"];
    "Check release exists" -> "Release exists?";
    "Release exists?" -> "Tell user: diff unavailable.\nLink to rn-diff-purge.\nAsk for closest match." [label="yes"];
    "Release exists?" -> "Tell user: version invalid.\nAsk for valid target." [label="no"];
}

Check release existence with: gh api repos/facebook/react-native/releases/tags/v{TARGET} (200 = exists, 404 = invalid version)

Do NOT proceed to Phase 2 without a valid, fetchable diff.

Step 3: Dispatch Analysis Subagent

Dispatch a general-purpose subagent (subagent_type: "general-purpose", max_turns: 15) using the prompt template in analysis-prompt.md (in this skill directory). Read that file to get the full prompt, then fill in the bracketed values.

Pass it:

• Current version
• Target version
• List of all intermediate versions (current exclusive, target inclusive)

Determining intermediate versions: List only the .0 minor releases between current and target (e.g., 0.74.0, 0.75.0), plus the exact target version. Do NOT guess patch versions — the subagent will fetch each release page and skip any that return 404. This keeps the version list short and deterministic.

The subagent fetches release notes for each intermediate version and returns a summary with complexity assessment.

Step 4: Present Results

Show the user:

1. Version validation results
2. Diff URL
3. Release notes summary (from subagent)
4. Complexity assessment (Simple / Moderate / Complex)

Ask: "Want to proceed with the upgrade execution?"

Phase 2: Execution (User Opts In)

Step 5: Dispatch Execution Subagent

Dispatch a general-purpose subagent (subagent_type: "general-purpose", max_turns: 30) using the prompt template in execution-prompt.md (in this skill directory). Read that file to get the full prompt, then fill in the bracketed values.

Pass it:

• The diff URL from Step 2
• Current and target versions
• Project root path

The execution subagent handles: fetching the diff, classifying files, applying changes with the skip strategy, and running post-upgrade tasks.

Step 6: Post-Execution Summary

After the execution subagent completes, summarize:

• Files modified
• Manual steps still required
• How to verify the upgrade (build both platforms, run tests)

Error Recovery

Failure	Action
Analysis subagent fails/times out	Re-dispatch once. If it fails again, manually fetch the target version's release notes and present a simplified analysis.
Diff URL returns 404	Follow the validation flow in Step 2. Do NOT proceed without a valid diff.
Execution subagent fails mid-upgrade	Report what was completed and what remains. The user can re-run execution for remaining phases.
Execution subagent reports dependency install failure	Do NOT re-dispatch. Present the error to the user — dependency conflicts need human judgment.

Common Mistakes

Mistake	Fix
Using the web UI URL instead of raw diff	Use raw.githubusercontent.com/react-native-community/rn-diff-purge/diffs/diffs/ format
Skipping intermediate release notes	Fetch ALL versions between current and target
Modifying App.tsx / user source code	Follow the skip strategy in execution-prompt.md
Running everything in main context	Dispatch subagents — release notes and diff parsing are token-heavy
Not cleaning caches post-upgrade	Always clean Metro cache, reinstall pods, clean Gradle