Transform my repo

Transform My Repo

Migrations die from optimism: the equivalent library that doesn't exist, the runtime behavior nobody knew was load-bearing, the big-bang rewrite that never ships. This skill plans transformations the evidence-first way — and its most valuable possible output is a well-argued "don't."

Division of labor: this skill answers whether to migrate, how hard, in what order, and with what safety net. The detailed implementation plan for each migration phase is a deep-plan run — do not duplicate that work here.

The Prime Directive (family rule)

No claim without evidence — on BOTH sides. Source facts need file:line. Target-stack facts (a library exists, a mechanism behaves a certain way) need a registry/docs citation with version, checked NOW — training-data memory of an ecosystem is not evidence, and "surely Python has an equivalent" is how migrations lose months.

Progress checklist

Copy this into your response and check items off:

Transform Progress:
- [ ] Step 0: Frame — source → target, driver, constraints, non-goals, feasibility questions
- [ ] Step 1: Source census — inventory + dependency, platform-coupling, operational censuses
- [ ] Step 2: Target ground truth — every dependency & mechanism verified in target ecosystem
- [ ] Step 3: Gap analysis — semantic gaps + per-module difficulty heatmap
- [ ] Step 4: Verdict — GO / PARTIAL / NO-GO as a 10–20 line brief  ⛔ user gate
- [ ] Step 5: Strategy — code + data parity, pattern, bridge, rollback, ONE-WAY tags, data migration plan, modernization sequenced separately
- [ ] Step 6: Assessment document — skeleton-first roadmap, spikes for unknowns, pre-mortem risks
- [ ] Step 7: Self-check + report

Step 0 — Frame the transformation

Use the arguments provided with the invocation (some platforms substitute them as $ARGUMENTS — [source → target] [project-root] [driver/reason]); otherwise infer from the repo and ask. Treat the given project-root as the source repo for every step; state which root you used in the report.

Pin down, before analyzing anything:

• Source → target, precisely (language+version, framework, deployment model).
• The driver — WHY migrate: performance, hiring, maintenance, licensing, business model (SaaS)? The verdict is only meaningful relative to the driver; "Go is nicer" and "PHP hosting blocks our SaaS pricing" produce different verdicts on identical code.
• Constraints: team skills, downtime tolerance, budget/deadline, data that must not be re-migrated twice.
• Non-goals: what explicitly stays as-is.
• Feasibility Questions — a numbered list of what the verdict needs answered ("does the target ecosystem cover the ORM?", "does the target runtime actually serve the perf driver?", "is there a seam where old and new can coexist?"). Steps 1–3 exist to answer this list: each finding cites the question number it answers, questions discovered mid-census are appended, and research is complete when every question is answered with evidence or explicitly tagged UNVERIFIED — not when every file has been read.
• Identify which transformation type(s) apply — see references/transformation-catalog.md; each type has its own extra checklist. Combinations (port AND SaaS-ify) multiply risk: recommend sequencing them, not doing both at once.

Step 1 — Source census

Inventory the source repo (reuse the know-my-repo discipline if that skill is available; otherwise a deep read: structure, data flow, wiring, tests, git trajectory). On top of that, three censuses specific to migration:

1. Dependency census — every runtime dependency with its role and how deeply its API is woven in (call-site count).
2. Platform-coupling census — every use of source-platform-specific behavior: runtime model (e.g. PHP's request-per-process state reset), language constructs with no direct target equivalent, OS/FFI calls, framework magic, numeric/string/encoding semantics the code relies on.
3. Operational census — deploy pipeline, environments, real data scale (row counts, traffic — migrating 100 rows and 100M rows are different plans), and background jobs (cron/queue) touching the paths that move. Migrations fail on ops as often as on code; this census feeds the coexistence bridge and cutover math in Step 5.

Everything with file:line. Also record test coverage per module — it determines parity-harness cost in Step 5.

Step 2 — Target ground truth

For EVERY census entry, verify in the target ecosystem — registry, official docs, source — with URL + version, fetched now:

Census entry	Target equivalent	Coverage	Evidence
<library / mechanism>	<package / built-in / none>	full / partial / missing	<registry or docs URL + version>

Rules:

• "Partial" must say what is missing (features, maturity, maintenance status — a last-commit-3-years-ago port counts as missing).
• Missing entries are the headline finding, each with its realistic options: write it yourself (estimate), keep a sidecar in the source language, change approach, or verdict-blocker.
• Verify the target's runtime model actually serves the driver (e.g. if the driver is performance, find benchmarks or write a spike — do not assume).
• No web access in this session? Degrade honestly: verify what local evidence allows (installed target toolchains, lockfiles, vendored source, offline docs), tag everything else UNVERIFIED — needs web check, and say plainly that the verdict is provisional until those are checked. Never fill the Evidence column from memory.

Step 3 — Gap analysis and difficulty heatmap

• Semantic gaps: behaviors that will silently differ after a faithful line-by-line port — typing discipline, concurrency model, error handling idioms, numeric precision, string/encoding, lifecycle/state model, transaction semantics. Each gap: where it bites (file:line) and how it will be handled or tested.
• Difficulty heatmap: score every module with the rubric in references/feasibility-rubric.md (size, dependency density, platform coupling, test coverage, churn). Output a ranked table — this answers "what will be hard" concretely and later dictates migration order.

Step 4 — The verdict ⛔

Apply the rubric and present, BEFORE designing anything further:

• GO — coverage and gaps manageable; expected cost proportionate to the driver.
• PARTIAL — migrate these modules, keep/bridge those; say which and why.
• NO-GO — the evidence says the driver is better served another way; name the alternative (targeted refactor, optimization, extraction, different target). A NO-GO with evidence is a successful outcome of this skill, not a failure.

Present it as a Verdict Brief — 10–20 lines in chat, not a document: the verdict, dependency coverage stats, worst gaps, heatmap top rows, estimated magnitude (S/M/L/XL per module group), the three worth-it answers, and any feasibility question still UNVERIFIED. Ask for the decision once. Stop and let the user decide. Only continue to Step 5 on an accepted GO/PARTIAL.

If the user cannot respond (headless/CI run), degrade honestly: on GO or PARTIAL, continue but tag the verdict UNCONFIRMED — awaiting user in the document's Verdict section; on NO-GO, write the assessment with the strategy and roadmap sections marked "not applicable — NO-GO" — designing a migration nobody approved is waste.

Step 5 — Migration strategy

Design the safety net before the route:

1. Behavioral parity harness first. Before any porting, pin current behavior: characterization/golden-master tests on the source for every module about to move, at its seams (HTTP responses, DB writes, file outputs). Untested behavior cannot be proven preserved — budget this honestly; it is often the largest single line item. This proves code parity; data parity is a separate gate (item 6) — code that behaves identically on top of silently corrupted data is not a successful migration.
2. Migration pattern — decide, don't menu: default is incremental with coexistence (strangler fig at a routing/API seam, branch-by-abstraction, module-by-module with an interop bridge). A big-bang rewrite requires proof it is unavoidable (tiny codebase, or no viable seam), not preference.
3. Coexistence bridge: how old and new run together during migration — API seam, message queue, sidecar, FFI — and how data stays consistent across both (single writer? sync? cutover-per-table?).
4. Cutover and rollback: per phase — shadow/dual-run with output diffing where feasible, feature flags, the exact rollback trigger and procedure. A phase without a rollback path is not a phase; it is a bet.
5. Classify every cutover action REVERSIBLE or ONE-WAY. ONE-WAY = undo cost rivals do cost: in-place/destructive data conversion, decommissioning the old system, a cutover after which the two stores diverge, a public API contract change. Each ONE-WAY action needs explicit user confirmation before its phase runs — in headless runs, carry it into the document marked UNCONFIRMED. REVERSIBLE actions just need their rollback path named.
6. Data migration plan — whenever the data's shape or owner changes, not just on a database swap. A language port, a SaaS-ification, or a monolith split can all reshape or re-own data while the engine stays put. Plan four things, each with file:line/schema evidence:
   • Field-level mapping — old shape → new shape, column by column; name every default, type coercion, and split/merge. A renamed or restructured schema (see Modernization vs. parity below) makes this mandatory, not optional.
   • Backfill & dirty-data handling — legacy data almost never satisfies the new constraints: bad encodings, orphaned rows, duplicates, values that violate the target's types or NOT NULLs. Census the offenders and decide per class (clean, quarantine, or reject) — silently dropping them is data loss.
   • Move mechanism — dump/restore vs dual-write vs CDC, chosen by volume × allowable downtime (Type G in the catalog).
   • Reconciliation gate (data parity) — the bulk check that proves the move was faithful: row counts match, checksums/aggregates agree, referential integrity holds, a sample diff is clean. This is distinct from the code parity harness and MUST pass before an old store is decommissioned. Name its rollback: how the source stays authoritative until reconciliation is green.

Modernization vs. parity

Legacy source is often a mess — vanilla code with SQL scattered across files, cryptic table/column names, dead branches. The temptation is to clean it up while porting. Resist: mixing cleanup into the port destroys parity-testing (you can no longer tell whether a behavior changed because of the port or the cleanup). The rule:

• Port to parity first, carrying the mess faithfully; prove code + data parity; then modernize as a separate, deliberate phase on the roadmap.
• Following the target's standards/idiom is part of the port, not optional cleanup (a port that fights the idiom fails review forever) — but cosmetic/structural cleanup (renaming, re-layering, dead-code removal) is the separate phase.
• Renaming schema/tables/columns uses expand-contract, never a rename at cutover: add the new name → backfill → dual-write both → switch readers → drop the old name. Record every rename in a rename map so the data migration plan (item 6) can map old rows to new shape.

Step 6 — Write the assessment document

Write to docs/TRANSFORM.md (or user-chosen path) following references/assessment-template.md: verdict + evidence, censuses, gaps, heatmap, strategy, and a phased roadmap where each phase is sized to be one deep-plan run, ordered by the heatmap (start with a low-risk, representative module to calibrate real cost — never the hardest one), each with parity gate + rollback point.

Two roadmap non-negotiables:

• Phase 1 is a walking skeleton, not a code drop: the calibrator module runs end-to-end in the target stack — built, deployed through the real pipeline, serving traffic through the actual coexistence bridge. "Ported and unit-tested" parks the integration risk (build, deploy, bridge, data) at the end of the migration, which is where migrations die.
• Every UNVERIFIED tag and every missing census entry that survives into the roadmap becomes a named, timeboxed spike task placed FIRST in the phase that depends on it (e.g. "Spike: prove <target lib> handles <feature> — 1 day"). No unknown may sit silently under a migration phase.

Step 7 — Self-check and report

• Every target-ecosystem claim has URL + version. Every source claim has file:line. Zero "surely the target has this" — grep the document for UNVERIFIED and verify the count matches section 10.
• Every Step 0 feasibility question is answered with evidence or listed as UNVERIFIED in the document — and every surviving UNVERIFIED/missing entry has a named spike task first in the phase that depends on it.
• The verdict follows from the evidence shown, not from enthusiasm either way — and it was presented as a Verdict Brief (or, headless, tagged UNCONFIRMED).
• Every ONE-WAY cutover action is user-confirmed or marked UNCONFIRMED; every REVERSIBLE action names its rollback path.
• If the data's shape or owner changes, the document has a data migration plan (field mapping, dirty-data handling, move mechanism, reconciliation gate) — not just a "migrate the data" bullet. Data parity (row counts/checksums/integrity) is a named gate, separate from code parity.
• Any cleanup/renaming is sequenced as its own phase AFTER parity, with a rename map and expand-contract migrations — never folded into the port.
• The risk register came from the pre-mortem — no risk that could be pasted into a different migration's assessment unchanged.
• Roadmap Phase 1 is a walking skeleton (deployed end-to-end through the bridge), and the operational census (deploy, data scale, background jobs) is reflected in the cutover plan.
• The user could hand Phase 1 of the roadmap to deep-plan right now.
• Report: verdict, top 3 hardest things (per the heatmap), missing equivalents, and the recommended first slice.

When things go wrong

Situation	Response
Target ecosystem unreachable (no web access)	Degrade honestly (Step 2): verify what local evidence allows (installed toolchains, lockfiles, vendored source, offline docs), tag everything else UNVERIFIED — needs web check, state plainly verdict is provisional. Never fill Evidence column from memory.
Dependency has no target equivalent and no acceptable workaround	Missing entry becomes headline finding (Step 2). Realistic options: write it yourself (estimate), keep sidecar in source language, change approach, or verdict-blocker. If blocker touches core → NO-GO.
User cannot respond to Verdict Brief (headless/CI run)	Degrade honestly (Step 4): on GO/PARTIAL continue but tag verdict UNCONFIRMED — awaiting user in document; on NO-GO write assessment with strategy/roadmap marked "not applicable — NO-GO". Never design migration nobody approved.
Feasibility question remains unanswered after Step 3	Tag UNVERIFIED explicitly (Step 0 rule), list in document section 10, create named timeboxed spike task FIRST in the phase that depends on it (Step 6). No unknown may sit silently under a migration phase.
ONE-WAY cutover action needed but user unavailable for confirmation	Mark UNCONFIRMED in document (Step 5). Carry into roadmap phase with confirmation status visible. Never execute destructive action without explicit user sign-off.
Migration stalls at 60%, both stacks running forever	Classic risk — gets explicit trigger and answer in risk register (Step 6). Define DONE criterion up front (e.g. "no direct mysqli_query outside repository layer"); strangler must finish strangling.