| name | reshaped-v3-v4 |
| description | Migrates apps from Reshaped v3 to v4 breaking API changes. Use when the user asks to upgrade to v4, fix breaking changes, or migrate deprecated Reshaped APIs. |
Reshaped v3 to v4 Migration
Apply documented and safe migrations from Reshaped v3 to v4 with minimal edits and explicit reporting.
Scope and inputs
- Canonical migration recipes live in
changes/*.md in this skill directory.
- Each file in
changes/*.md represents one breaking-change topic.
- Follow documented migration paths from those files first; if there is no automated migration path available and you don't have a high confidence solution – don't edit the code and add this case to the migration report.
- Prefer deterministic, low-risk edits over broad refactors.
Operating rules
-
Confirm migration scope
- Identify which package(s), app(s), or folders should be migrated.
- If scope is unclear, ask a focused clarifying question before editing.
-
Build an ordered migration checklist
- List all available files in
changes/*.md.
- Process them one by one in a stable order (for example: alphabetical by filename).
- For each change file, determine whether it applies to the target scope.
-
Apply migrations conservatively
- Use exact symbol/prop matching when possible.
- Keep behavior unchanged unless the migration doc requires behavior changes.
- Avoid unrelated cleanup while migrating.
- Preserve user-authored custom logic and styling intent.
-
Validate after batches of edits
- Run local checks relevant to the repo (typecheck, lint, tests, build, or targeted checks).
- If a migration introduces uncertainty, stop and verify before continuing.
-
Report outcomes explicitly
- Produce a migration report after edits.
- Include per-migration status, component counts, confidence, and manual actions.
Per-change execution loop
For each migration file in changes/*.md:
- Read the migration file fully.
- Extract:
- Trigger pattern (what old API usage to find).
- Target pattern (what v4 usage should replace it).
- Constraints, caveats, and exceptions.
- Search the scoped codebase for matches.
- Classify each match:
- Safe automated migration.
- Requires contextual/manual decision.
- Not applicable/false positive.
- Apply changes for safe matches.
- Record report data for this migration, even when no matches were found.
Confidence model
Use these confidence levels in the report:
high: mechanical replacement with unambiguous mapping and local validation passes.medium: mapping is mostly clear but depends on component context, composition, or styling intent.low: migration path is incomplete, risky, or requires product/UX intent to resolve.
For every medium or low item, include exact code locations that need review.
Required migration report
Create a report file in the workspace root named:
reshaped-v3-v4-migration-report.md
Report format:
# Reshaped v3 -> v4 Migration Report
## Scope
- Target: <folders/packages migrated>
- Date: <YYYY-MM-DD>
## Migration Results
### <migration name from file>
- Status: `completed` | `partial` | `not-applicable` | `blocked`
- Components updated: <number>
- Confidence: `high` | `medium` | `low`
- Medium/low review locations:
- `<path>:<line>` - <why review is needed>
- Notes: <key decisions, caveats>
- Manual steps (if any):
- <required human follow-up>
<!-- Repeat for every changes/*.md file -->
## Summary
- Total migrations processed: <number>
- Completed: <number>
- Partial: <>
- Not applicable:
- Blocked:
- Total components updated:
Handling missing automated paths
If a change file has no safe automated migration path:
- Mark status as
blocked or partial (depending on progress).
- Explain why automation is unsafe or impossible.
- Provide concrete manual remediation steps.
- Include precise locations for manual edits.
Communication style
- Be explicit and audit-friendly.
- Prefer short, factual notes over long explanations.
- Distinguish clearly between applied changes and recommendations.
