# Archaeology

> Investigate why code exists before changing it, using indexed git history (commit -> PR -> issue). Use when a git-fence warning fires, when the user asks why code exists or whether it is safe to delete, before removing a check/workaround/special case that looks unnecessary, or when simplifying old code.

- Skill: `mythren/archaeology` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mythren/archaeology`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mythren/archaeology/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mythren (https://skillmd.com/u/mythren)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mythren/archaeology

---


# Code Archaeology

Old code that looks wrong is often a fence someone built on purpose. Before
removing or simplifying it, recover the reason it exists.

## Prerequisite

If `git-fence` is not on PATH (plugin-only install), substitute
`python3 "$CLAUDE_PLUGIN_ROOT/bin/git-fence"` for `git-fence` in every
command below (or locate the plugin under `~/.claude/plugins/`).

The repo must be indexed once (fast - thousands of commits per second):

```bash
git-fence index --github   # --github enriches with PR/issue data via gh
```

If `git-fence stats` errors with "no index", run the index command first.

## Workflow

1. **Ask the index first.**
   - `git-fence why <file> <line>` - full provenance of one line: commit, PR, linked issues.
   - `git-fence why <file>` - all fix-linked commits that touched the file.
   - `git-fence check <file> <start> <end>` - load-bearing commits in a line range.

2. **Read the actual discussion when stakes are high.** The index gives you PR
   and issue URLs. For security fixes, regressions, or anything you plan to
   delete, fetch the PR/issue with `gh pr view <n>` / `gh issue view <n>` and
   read why the change was made and what alternatives were rejected.

3. **Dig deeper when the index has no answer.**
   - `git log -L <start>,<end>:<file>` - full evolution of a line range,
     including commits that predate squash merges.
   - `git log --follow --oneline -- <file>` - history across renames.
   - A test added in the same commit is the best spec for what the code
     protects. Check with `git show <sha> --stat`.

4. **Decide with evidence.** Only after you can state *what bug the code
   prevents* decide whether removal is safe. If the original bug can no longer
   occur (dependency removed, API changed), say so explicitly and delete with
   confidence. If you cannot reconstruct the reason, keep the code and say why.

## Responding to a git-fence hook warning

When a `[git-fence]` warning appears during an edit, do not silently proceed
or silently back off:

1. Run `git-fence why` on the flagged lines.
2. State in one sentence what the original bug was.
3. Confirm your edit does not reintroduce it (keep the guard, keep the test),
   or adjust the edit so it does not.