code-archaeology

name	code-archaeology
description	Use when a codebase has accumulated technical debt including dead code, legacy fallbacks, circular dependencies, duplicate types, weak typing, defensive programming slop, or error handling anti-patterns that need systematic excavation and cataloging before restoration.
platform	claude-code
tools	["Bash","Agent","Read","Write","Edit","Glob","Grep","Skill","TodoWrite"]

Code Archaeology

Systematic excavation of a codebase to remove accumulated sediment—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop—while producing human-reviewable site reports before any artifacts are disturbed. Non-destructive by default.

Overview

Code Archaeology treats a codebase like an archaeological site. Each expedition removes a specific class of technical debt in a fixed order (stratigraphic dependencies). Reports are generated at every phase. In survey mode, zero files are modified. In excavate mode, mock patches are produced for human review. In restore mode, approved changes are executed.

When to Use

• Codebase has grown over years with unclear ownership
• Large amounts of commented-out, unused, or unreachable code exist
• Legacy polyfills, shims, or compatibility layers remain for EOL environments
• Circular dependencies block tree-shaking or slow builds
• Types are duplicated across files or use any/unknown excessively
• Error handling suppresses or swallows exceptions
• DRY violations create maintenance burden
• Team wants a full audit before refactoring

When NOT to Use

• Greenfield project with minimal code
• Codebase already has active refactoring in progress
• No test suite exists (baseline verification requires passing tests)
• Team cannot review generated reports before restoration

Expedition Order (Fixed)

The expeditions MUST run in this order due to stratigraphic dependencies:

1. Site Survey & Baseline — inventory, metrics, baseline capture
2. Dead Code Excavation — unused exports, unreachable functions, orphans
3. Legacy Stratum Removal — deprecated APIs, polyfills, shims
4. Circular Dependency Cartography — map and break cycles
5. Type Catalog Consolidation — deduplicate types
6. Type Restoration & Hardening — replace weak types
7. DRY Stratification — extract semantic duplications
8. Error Handling Stratigraphy — fix suppression/empty catch
9. Artifact Cleaning & Documentation — remove slop, update docs
10. Site Preservation & Final Catalog — verify, preserve records

Why this order: You cannot consolidate types before removing dead code (you might catalog code that should be discarded). You cannot DRY before untangling cycles (abstractions over cyclic deps create worse stratification).

Modes

Mode	File Changes	Reports	Use Case
survey	Zero	All	Initial audit, management review
excavate	Zero	All + mock patches	Pre-approval, team review
restore	Yes (HIGH confidence)	All	Executing approved changes
yolo	Yes (HIGH + MEDIUM confidence)	All	Unattended full restoration

With strict_mode: true, restore also applies MEDIUM confidence findings.

Constraints

• NEVER commit directly to main or master
• NEVER remove or modify code without writing a site report first
• NEVER guess types; flag uncertain replacements for human review
• ALWAYS run tests between phases; stop immediately on failure
• ALWAYS revert changes if a phase introduces test failures
• NEVER consolidate types before dead code and legacy removal
• NEVER remove try/catch from I/O or external input boundaries
• NEVER open an issue or cleanup PR from a vague finding; first pass the Actionability Gate below

Continuation Ledger

Before starting a new expedition, inspect existing .archaeology/ reports and, when GitHub access is available, recent PRs/issues for the same repository. Create or update .archaeology/continuation-ledger.md with findings that still matter:

Finding	Current status	Evidence checked this run	Next action
file:line or issue/PR link	open / fixed / superseded / needs-more-evidence	command, diff, or search	PR / issue / skip / revisit later

Use this ledger as the deduplication gate. Mark findings fixed when the current base branch already contains the remedy, carry blocked items forward as needs-more-evidence with the exact missing artifact or platform, and improve existing PRs/issues instead of creating duplicates. If prior context is unavailable, record that limitation and proceed with local evidence only.

Before recommending a PR or issue, run a duplicate preflight using the strongest available signals: recent reports, the continuation ledger, current git log, and when authenticated, gh pr list --search <file-or-symbol> plus gh issue list --search <file-or-symbol>. Record the matched item or none in the finding evidence so the next run does not rediscover the same debt.

Actionability Gate

Before recommending a PR or issue, ensure each finding has enough context for a future run to act without rediscovery:

• file:line location.
• Evidence from tool output, reference search, or manual trace.
• Confidence plus the reason for that confidence.
• Guardrails, such as public APIs, generated files, ABI/runtime hooks, or I/O boundaries not to touch.
• The narrowest verification command or platform/runtime requirement.
• A concrete proposed action: remove, refactor, document, regenerate, or human-review.

If any field is missing, keep the finding in the report as needs-more-evidence instead of filing an issue or proposing a source-edit PR. Prefer one complete, high-confidence fix over several vague findings.

Native/C++ Evidence Checklist

When auditing C, C++, Objective-C, game-runtime, hook, ABI, or generated-header code, add this block to the report before recommending restore-mode edits:

## Native Evidence
- Compile database: present/missing/partial/stale; path:
- Coverage gaps: uncovered source examples or missing generated headers:
- Source freshness: newest source newer than compile database? yes/no/examples:
- ABI/runtime guardrails: exported symbols, hooks, packed structs, offsets, or calling conventions to preserve:
- Safe verification ladder: narrow syntax/lint command first, then project build/test:

Do not make broad dead-code claims from missing, partial, or stale compile databases. Convert those findings into needs-more-evidence or an issue unless the proposed change is backed by a direct trace that does not depend on full compile database coverage.

Progress Tracking

Use TodoWrite to track expedition phases. Create one todo per phase at the start of the expedition, mark each in_progress before starting it, and completed immediately after it passes verification. Never batch completions.

Phase 1: Site Survey & Baseline
Phase 2: Dead Code Excavation
Phase 3: Legacy Stratum Removal
Phase 4: Circular Dependency Cartography
Phase 5: Type Catalog Consolidation
Phase 6: Type Restoration & Hardening
Phase 7: DRY Stratification
Phase 8: Error Handling Stratigraphy
Phase 9: Artifact Cleaning & Documentation
Phase 10: Site Preservation & Final Catalog

Parameters

Parameter	Default	Description
repo_path	.	Target repository
language	typescript	Primary language
mode	survey	survey, excavate, restore, or yolo
yolo	false	If true, force mode: yolo
strict_mode	false	Auto-restore medium-confidence findings
test_command	npm test	Recorded session default only; verification uses CODE_ARCHAEOLOGY_TEST_COMMAND for operator-approved overrides
typecheck_command	npx tsc --noEmit	Recorded session default only; verification uses CODE_ARCHAEOLOGY_TYPECHECK_COMMAND for operator-approved overrides
branch_name	refactor/archaeology	Git branch to create

Language-Specific Tooling

Language	Dead Code	Dependencies	Types	DRY
TypeScript	knip, unimported	madge	tsc	jscpd
JavaScript	knip, depcheck	madge	N/A	jscpd
Python	vulture	pydeps	mypy	pylint
Go	deadcode, staticcheck	godepgraph	go vet	golangci-lint
Rust	cargo-udeps, rustc	cargo-deps	rustc	clippy

If tools are missing, falls back to AST-based manual analysis.

Quick Reference

# Survey only (zero changes, default)
/code-archaeology

# Survey only, explicit
/code-archaeology-survey

# Generate mock patches for review
/code-archaeology-excavate

# Apply approved changes
/code-archaeology-restore

# Full unattended restore (HIGH + MEDIUM confidence)
/code-archaeology --yolo

Output Artifacts

All artifacts are written to .archaeology/:

• site_survey.md — baseline inventory and stratum graph
• expedition1-report.md through expedition8-report.md — per-expedition findings
• FINAL_CATALOG.md — completed excavation metrics and recommendations
• excavation_log.txt — git diff --stat

Expedition Prompts

Detailed instructions for each expedition are in the plugin's prompts/ directory:

• discovery.md — Phase 0: Site Survey
• dead_code.md — Expedition 1
• legacy.md — Expedition 2
• dependencies.md — Expedition 3
• types_consolidate.md — Expedition 4
• types_harden.md — Expedition 5
• dry.md — Expedition 6
• errors.md — Expedition 7
• polish.md — Expedition 8
• final_verify.md — Phase 9

Common Mistakes

• Running restore before reviewing survey reports — always review first
• Skipping test runs between phases — failures must be caught immediately
• Consolidating types before removing dead code — creates cataloging work for discarded code
• Removing I/O boundary try/catch blocks — these protect against external failures
• Guessing types during hardening — flag uncertain replacements for review instead