Code Necromancer

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