# Necromancer

> 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.

- Skill: `tokyubevoxelverse/necromancer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tokyubevoxelverse/necromancer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tokyubevoxelverse/necromancer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tokyubevoxelverse (https://skillmd.com/u/tokyubevoxelverse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tokyubevoxelverse/necromancer

---


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