---
type: skill
domain: development
links: [Corpus_Callosum/CONSTITUTION.md, PULSE_OS.md]
---

# CODE_ARCHEOLOGIST.md
> **ROLE:** HERITAGE ENGINEER
> **TRIGGER:** "EXPLAIN THIS" / "WHY" / "HISTORY"

## Step-by-Step Protocol
1. **Start with `git blame`** — run `git blame -w -C <file>` (ignore whitespace, detect moves). Identify the commit that introduced the code in question. Note: `-C` detects code moved between files.
2. **Read the commit in context** — `git show <commit_hash>` to see the full changeset. Read the commit message for intent. Check if it references an issue or PR number.
3. **Trace the evolution** — `git log --follow -p <file>` to see every change to the file over time. Use `git log --all --grep="keyword"` to find related commits across branches.
4. **Bisect to find regressions** — `git bisect start`, `git bisect bad HEAD`, `git bisect good <known_good_commit>`, then test at each step. Automate: `git bisect run python -m pytest tests/test_specific.py`. Bisect finds the breaking commit in O(log n) steps.
5. **Document findings** — save the archaeological dig results with `pulse_save.py`. Record: what the code does, why it was written that way, what constraints existed, and whether those constraints still apply.

## Metrics & Thresholds
- **Blame depth:** trace at least 3 commits back (not just the last change)
- **Bisect efficiency:** should find regression in <=20 steps for any repo <100K commits (log2 math)
- **Context coverage:** every "why" explanation must reference a specific commit hash
- **Documentation rate:** 100% of archeological digs produce a written finding in Evidence/

## Good Example
```bash
# Full archeological dig workflow
# Step 1: Who wrote this and when?
git blame -w -C Autonomic_System/Daemons/pulse_worker.py

# Step 2: What was the full changeset?
git show e486dab --stat  # see files changed
git show e486dab         # see full diff + message

# Step 3: How did this file evolve?
git log --follow --oneline Autonomic_System/Daemons/pulse_worker.py

# Step 4: When did this test start failing?
git bisect start
git bisect bad HEAD
git bisect good 6580dae
git bisect run python -m pytest tests/test_worker.py -x

# Step 5: Find all commits mentioning "dispatcher"
git log --all --grep="dispatcher" --oneline
```

## Anti-Patterns
1. **Shallow blame** — only looking at the last commit; the real "why" is often 3-5 commits back. Use `git log -p` not just `git blame`.
2. **Deleting "dead" code without understanding it** — what looks unused might be called dynamically or via config. Verify with `grep -r "function_name"` across the entire repo first.
3. **Undocumented digs** — if you spent 15 minutes understanding code, save the finding. The next agent will hit the same question.

## Tools to Use
- `python Autonomic_System/Utilities/Tools/brain_query.py --query "why does <module> work this way"` — check if someone already answered this
- `python Autonomic_System/Utilities/Tools/pulse_relay.py --tasks "Code Dig:<domain>:fast"` — delegate shallow digs to fast-tier agents
- `python Autonomic_System/Utilities/Tools/pulse_save.py --agent archeologist --learnings "what you found"` — persist dig results

## Verification Checklist
- [ ] `git blame -w -C` used (not plain `git blame`) to catch moved code
- [ ] Commit message and full diff reviewed (not just the blamed line)
- [ ] At least 3 commits of history traced for the code in question
- [ ] Finding documented with commit hash references in Evidence/ or brain
- [ ] If regression found via bisect, root cause commit identified and recorded
