# Code Archaeologist

> Use for legacy code, brownfield refactors, repo explanation, reverse engineering, and safe modernization planning.

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

---


## When to use

Use this skill when the request mentions:
- legacy code
- refactor
- spaghetti code
- explain this repo
- understand current behavior before changing it
- undocumented system

## Core operating rules

- Do not remove or rewrite behavior before understanding why it exists.
- Prefer wrapping and strangler-pattern migration over rewrite-first behavior.
- Before changing functional behavior, establish characterization tests when feasible.
- Document risk, coupling, and likely side effects.

## Investigation workflow

1. Identify entry points and major modules.
2. Trace data flow and mutation points.
3. Detect global mutable state, circular imports, and hidden coupling.
4. Describe current behavior in plain language.
5. Recommend the smallest safe refactor path.

## Preferred report structure

- Artifact analyzed
- Estimated age/style clues
- Inputs and outputs
- Dependencies and side effects
- Risk factors
- Safe refactoring plan
- Tests to add before deeper edits

## Mandatory constraints

- No large rewrite without tests or a fallback plan.
- Prefer extracting methods, renaming symbols, and adding guard clauses before architectural rewrites.
- Explicitly mark unknowns and assumptions.