Code Necromancer
Tagline: Raise dead codebases from the grave
Systematic framework for understanding, resurrecting, and modernizing legacy codebases.
When to Activate
✅ Use when:
- Inheriting a codebase with 5+ repos and no documentation
- Resurrecting a product dormant for 2+ years
- Joining a company with significant technical debt and tribal knowledge loss
- Performing due diligence on acquired codebases
- Modernizing legacy systems without breaking existing functionality
❌ NOT for:
- Greenfield projects (start fresh instead)
- Well-documented active codebases
- Simple bug fixes in maintained systems
The Three Phases
Phase 1: ARCHAEOLOGY
Objective: Create a complete map before touching anything.
| Output | Description |
|--------|-------------|
| repo-inventory.json | All repos with metadata, languages, activity |
| dependency-graph.mmd | Inter-repo and external dependencies |
| architecture-diagram.mmd | Visual system topology |
| tech-stack-matrix.md | Language/framework versions per repo |
| maturity-assessment.md | Code quality, test coverage, docs quality |
| missing-pieces.md | Gaps, orphaned repos, broken integrations |
Process: Inventory → Deep Scan → Cross-Reference → Visualize → Assess
→ See references/archaeology-guide.md for detailed techniques.
Phase 2: RESURRECTION
Objective: Get the system running in development.
| Output | Description |
|--------|-------------|
| dependency-audit.md | Outdated packages, vulnerabilities, breaking changes |
| environment-variables.md | All required env vars with defaults |
| secrets-needed.md | API keys, certs, OAuth credentials |
| infrastructure-status.md | Cloud resources, what exists vs deleted |
| resurrection-blockers.md | Critical issues preventing launch |
| integration-tests/ | Tests verifying components work and communicate |
Process: Audit Dependencies → Map Environment → Check Infrastructure → Write Tests → Document Blockers
→ See references/integration-test-patterns.md for resurrection test patterns.
Phase 3: REJUVENATION
Objective: Modernize while maintaining feature parity.
| Output | Description |
|--------|-------------|
| security-recommendations.md | Vulnerability fixes, compliance |
| modernization-roadmap.md | Prioritized upgrades with effort estimates |
| architecture-improvements.md | Scalability, performance, maintainability |
Process: Security First → Infrastructure (containerize, CI/CD) → Code Quality → Architecture
Key Commands
# List all repos in org
gh repo list ORG --limit 1000 --json name,primaryLanguage,pushedAt
# Dependency analysis
npm audit && npm outdated # Node.js
pip list --outdated && safety check # Python
go mod graph # Go
# Find env vars in code
grep -rn 'process\.env\|os\.environ' --include="*.js" --include="*.py"
→ See references/framework-detection.md for framework/stack identification.
→ See references/infrastructure-mapping.md for cloud resource discovery.
→ See references/dependency-patterns.md for dependency detection.
Anti-Patterns to Avoid
1. Premature Resurrection
What it looks like: Running npm install before reading any code
Why it's wrong: You'll fix the same bug 5 times; dependencies have changed
Fix: Complete archaeology first; understand before touching
2. Scope Creep
What it looks like: "Let's also refactor while we're here" Why it's wrong: Scope explosion; never actually resurrect Fix: Strict phase separation; refactoring is Phase 3
3. Big Bang Updates
What it looks like: Update all dependencies in one commit Why it's wrong: Something breaks, no idea what Fix: Update incrementally; test after each
4. Ignoring Tests
What it looks like: "It runs, ship it" Why it's wrong: Regression city; no baseline for changes Fix: Write resurrection tests as you go; they prove progress
5. Undocumented Changes
What it looks like: "I fixed it but forgot what I changed" Why it's wrong: Tribal knowledge returns; next person is you in 6 months Fix: Document everything you learn and change
6. Trusting Old Documentation
What it looks like: Following README from 2019 Why it's wrong: APIs change, services get deprecated Fix: Verify every instruction; documentation lies
Success Metrics
Archaeology Complete When:
- [ ] All repos cataloged with metadata
- [ ] Dependency graph visualized
- [ ] Architecture diagram created
- [ ] Core vs peripheral repos identified
- [ ] Missing pieces documented
Resurrection Complete When:
- [ ] All services start locally
- [ ] Services can communicate with each other
- [ ] Integration tests pass
- [ ] At least one full user flow works
Rejuvenation Complete When:
- [ ] No critical security vulnerabilities
- [ ] All dependencies reasonably current
- [ ] CI/CD pipeline working
- [ ] Documentation current
- [ ] Team can develop new features
References
→ references/archaeology-guide.md - Deep code archaeology techniques
→ references/dependency-patterns.md - Dependency detection across ecosystems
→ references/framework-detection.md - Framework/stack identification
→ references/infrastructure-mapping.md - Cloud resource discovery
→ references/integration-test-patterns.md - Resurrection test patterns
Templates
→ templates/repo-inventory.json - Repository catalog
→ templates/archaeology-report.md - Phase 1 output
→ templates/resurrection-plan.md - Phase 2 output
→ templates/rejuvenation-roadmap.md - Phase 3 output