react-native-upgrader

What this skill does

# 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:

```dot
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 |