necromancer

name	necromancer
description	Resurrect a dead repository. Use when a project no longer installs, builds, or runs because it has aged — broken dependencies, deprecated APIs, dead tooling, registry rot, runtime drift. Revives it incrementally, keeping a verified working state at every step.

Necromancer

The repository in front of you used to work. Your job is to make it work again with the smallest possible set of changes, proving each step. This is a resurrection, not a rewrite: no refactors, no style changes, no "while I'm here" modernization. Behavior stays identical; only what is required to live again may change.

The Laws

1. Never big-bang upgrade. One dependency (or one tightly coupled group) at a time. A repo that fails with forty simultaneous errors after a bulk update is deader than when you started.
2. Every step ends in a verified state. Install, build, and (where possible) test after each change. If a step can't be verified, do not stack another change on top of it.
3. The lockfile and CI config are the death certificate. They record the exact world in which this code last lived — runtime versions, dependency versions, services. Trust them over the README.
4. Keep the log as you go. Every failure, every fix, every substitution goes into the resurrection report. Future maintainers need to know what the knife touched.
5. If the repo is under git, checkpoint. Commit after each verified stage so any single step can be rolled back alone. Ask before committing if the working tree wasn't clean when you arrived.

Phase 0 — Autopsy (read-only)

Establish what this project was before touching anything:

• Stack and versions. Lockfiles (package-lock.json, yarn.lock, poetry.lock, Pipfile.lock, Gemfile.lock, go.sum, Cargo.lock), version pins (engines, .nvmrc, .python-version, runtime.txt, rust-toolchain), Dockerfiles.
• Time of death. The last commit date. Note what the ecosystem looked like then — that date decides which runtime you resurrect against first.
• The last known-good environment. CI configs (.github/workflows, .travis.yml, Jenkinsfile, appveyor.yml) list the exact runtime matrix that last passed. This is often the single most valuable artifact in the repo.
• External requirements. Databases, services, API endpoints, env vars, system libraries. Note which external services may themselves be dead now.
• The promise. What does "working" mean for this repo — a server that answers? a CLI that runs? a library whose tests pass? Write down the finish line before you start walking.

Phase 1 — Time-of-death baseline

Try to install and build exactly as documented, with no fixes. Capture every error verbatim. Classify each failure:

Class	Signature	Typical cure
Runtime too new	native-module build explosions, syntax errors in old tooling	Pin the period-correct runtime
Dead dependency	404 from the registry, archived upstream	Maintained fork or nearest equivalent
Registry / URL rot	git deps pointing at moved or deleted repos, dead tarball URLs	Repoint or vendor
Breaking API change	Installs, but call sites are wrong at build/run time	Read the migration guide, patch call sites
Dead tooling	The build tool itself won't run	Upgrade tool + its config together, as one unit

Do not fix anything in this phase. You are diagnosing, not operating.

Phase 2 — Choose the strategy

Path A — period-correct first (default when the repo has been dead more than ~2 years). Recreate the environment the lockfile and CI describe — nvm/fnm, pyenv, rbenv, or a container running the old runtime — and get the repo working as it was. This proves the code itself is sound and gives you a green baseline to walk forward from. Then modernize incrementally, only as far as actually needed.

Path B — walk forward directly. If the baseline failures are few and shallow, fix them in place against a current runtime.

If the request was just "make it run," a period-correct working state may already be the finish line. Confirm how modern the result needs to be before walking the whole dependency tree forward.

Phase 3 — The revival loop

Repeat until the finish line:

1. Pick the one failing or most-blocking thing. Major versions move one hop at a time (14 → 15 → 16, never 14 → 19) whenever the changelog shows breakage between hops.
2. Update it. For each major hop, find the release notes or migration guide (CHANGELOG.md, GitHub releases, "migrating from vX" docs) and patch call sites from the guide, not from guesswork.
3. Coupled sets move together: a build tool and its plugin ecosystem, a framework and its router, a test runner and its transforms. Treat each set as one step.
4. Dead upstream? Prefer, in order: the community-maintained fork with real adoption → the modern equivalent with the closest API → vendoring the old code with a note. Record every substitution.
5. Rebuild, rerun, retest. Green → log it, checkpoint it, next. Red in a new place → that's progress; loop. Red in the same place → revert the step and take a different route rather than stacking fixes on a broken base.

No tests? Before entering the loop, write a minimal smoke test that exercises the repo's promise (the server answers on its port, the CLI's main command exits 0, the library's core function returns something sane). The loop needs a verifier, or "it builds" becomes the lie you ship.

Phase 4 — Prove it lives

Building is not living. Run the thing the repo exists to do, end to end: start the server and hit it, run the CLI against real input, import the library and call it. Run the full test suite. Then prove install-from-scratch: delete the dependency directory / environment and reinstall clean, once.

Phase 5 — The resurrection report

Write RESURRECTION.md at the repo root:

• Cause of death — what actually broke and why. It is usually two or three root causes, not forty.
• What changed — a table of dependency: old → new, one line on why each moved.
• Substitutions — anything replaced by a fork or equivalent, with reasoning.
• Scars — what remains fragile: untested paths, versions pinned for a reason, deps still years behind, security advisories deliberately deferred.
• Proof of life — the exact commands that verify it works.

Edge cases

• No lockfile — reconstruct one: resolve each dependency to the newest version released before the last-commit date, install, lock, and treat that as the baseline.
• Security advisories in old pins — flag them in the report; do not silently jump a major "for security" mid-resurrection. Stabilize first, then upgrade deliberately.
• Config pointing at dead external services — stub or mock just enough to reach a verifiable state, and list it under Scars.
• Monorepos — resurrect leaf packages first, then the packages that depend on them.