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

```bash
# 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