--- title: "Codebase history researcher" type: "agent" url: "https://useaiblocks.com/agents/agency-specialized-codebase-archaeologist" updated: "2026-11-03" first_published: "2026-10-26" job: "Write down how work gets done" tested: true licence: "MIT" source: "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.md" instructions: "https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist/SKILL.md" --- # Codebase history researcher > Find silent mismatches in code built over many AI sessions, such as reversed fallbacks, duplicate logic and stale docs, ranked by risk with files named. Give your AI a repo and its history. It looks for places where one file assumes something another file changed, such as two helpers that disagree. You get a drift registry with every finding tied to files, a risk level and the likely cause. Free agent for the job "Write down how work gets done" · Level: intermediate · Thinking: high · Tested · Updated 2026-11-03 ## Links - Page: https://useaiblocks.com/agents/agency-specialized-codebase-archaeologist - Instructions (SKILL.md): https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist/SKILL.md - All files (zip): https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist.zip - JSON version: https://useaiblocks.com/agents/agency-specialized-codebase-archaeologist.json - In your AI: connect https://useaiblocks.com/mcp and ask "Use AI Blocks to get agency-specialized-codebase-archaeologist" ## What it does When several AI tools and sessions build one codebase, each one writes with no memory of the others. The code runs, but the layers do not line up. One file turns cents into dollars, and another already did. A fallback is written backwards. A README describes a flow that no longer exists. A linter finds none of this, because each file looks fine alone. This codebase archaeologist agent reads the code in layers. It groups the history into eras, compares the same kind of file across eras, and lists every job that has more than one implementation. Then it runs two checks that most reviews skip: what each event handler assumes already exists, and what unit each money or quantity value is in. It reports and does not fix. It never blames a person or a tool. If it cannot tell whether a mismatch is a bug or a choice, it says so and does not guess a severity. ## What you give it - The repo, as files your AI can open, such as a folder, a zip or a project open in Claude Code - The git history, or the output of git log with dates (optional but it makes the eras far clearer) - Where to look, such as orders and payments, or the whole repo - Your README and docs, to compare with the code (optional) - Any earlier drift registry, so this run can check what stayed fixed (optional) ## What you get - A drift registry with four views, by finding, by era, by responsibility and by risk - Each finding with the files, the failure it could cause, a severity and its likely origin - A list of event handlers checked, marked safe or unguarded - A list of money and quantity values traced, with the unit at each step - Dead code, doc-versus-code mismatches and a cleanup order - A list of the files it read and the ones it did not ## Example: what goes in and what comes out ### What goes in - Your repo, as a folder, zip or open project - The git log with dates (optional) - The area to audit, such as orders and payments - Your README and docs (optional) ### Before you start - An AI that can open files, such as Claude Code, Codex or a chat that takes a zip ### What comes out - **Drift registry**: Four cross-linked views of every finding, by finding, by era, by responsibility and by risk. - **Finding detail**: For each serious finding, the files, what each side does, the risk and the likely origin. - **Checked and safe**: Handlers and values it checked and found safe, so you know they were covered. - **Dead code**: Files with no remaining references and the thing that replaced them. - **Doc versus code**: Each doc claim that no longer matches the code, with what the code does now. - **Cleanup order**: Critical, moderate and cosmetic items in the order to fix them. ## The layout of every result ```text DRIFT REGISTRY Scope: | Files read: | Not read: VIEW 1, BY FINDING | | | | VIEW 2, BY ERA | | | VIEW 3, BY RESPONSIBILITY | | VIEW 4, BY RISK Critical: | Moderate: | Cosmetic: FINDING DETAIL (one per critical or moderate finding) Files: | Pattern found: | Risk: | Likely origin: | Fix direction: CHECKED AND SAFE | DEAD CODE | | DOC VERSUS CODE | | CLEANUP ORDER Critical: | Moderate: | Cosmetic: ``` ## Use it when - A project grew over months with several AI coding tools, and you do not trust that the parts agree. - Money, orders or stock numbers come out slightly wrong and no single bug explains it. - You inherited a codebase and want to know what was half-migrated and left behind. - Before a big refactor, you want to know which files are safe to build on. ## Skip it when - You are new to a repo and want to know how it is laid out. Use the Codebase onboarding planner. - You want a code review of a pull request or one file. Use the Code Reviewer agent or the Bug and security code reviewer. - You want to find out where docs no longer match one feature. Use the Code and documentation consistency checker. - Something is broken in production now. Debug it first, then use this for the wider cleanup. ## How to use it 1. Give your AI the code. A tool that opens folders and runs git works best, such as Claude Code or Codex. Both need a paid plan or account. A plain chat works without one, but you must paste the git log, the file list and the files you suspect. 2. Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat. 3. Say where to look. For example, "Audit the orders and payments code for drift. Here is the git log." Pick one area on a large repo. 4. Read the critical findings first. For each one, open both files and check that the mismatch is real. 5. Fix one finding at a time, in both files. Then rerun with the registry attached to see that it stayed fixed. 6. Hand confirmed findings to a person or tool that can edit the code. This agent does not change files. ## Check your result - The result addresses your actual task and cites the evidence used. - Examples, role-play experience and targets are kept separate from verified results. - Claims of tests, memory, tool access or completed actions match what actually happened. ## What to do next - [Developer docs writer](https://useaiblocks.com/skills/developer-docs-writer): Developer docs writer - [Process guide revision reviewer](https://useaiblocks.com/skills/process-doc-freshness-keeper): Process guide revision reviewer ## Sources and credits - From Michael Sitarzewski and Agency Agents contributors: https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.md, shared under the MIT licence (original name: Codebase Archaeologist). - [Codebase Archaeologist](https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.md), Michael Sitarzewski and Agency Agents contributors: Original agent profile, preserved in references/source-agent.md; AI Blocks adds setup and review instructions. ## Instructions (SKILL.md) ## Codebase Archaeologist agent Audit a codebase that several sessions or tools have changed over time. Find the places where one part silently assumes something another part changed. Report findings with evidence. Do not rewrite or refactor. The full profile, with its registry formats and rules, is in [the original role profile](references/source-agent.md). Read it if you can. This file is enough to run the job on its own. ### Before you start Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait. **What you need** (use your own material or the linked skill): - **A codebase** (yours): a project's code, in a folder or repo the AI can open. **Makes it better (optional):** - **Your question** (yours): the decision or problem, and what a good outcome looks like. - **A document** (yours): a finished document, such as a Word file, a PDF or a page of notes. How to start: 1. **Look first.** Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name. 2. **Check what's missing.** Look for a codebase, your question, a document. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps. 3. **Do the job.** Follow the skill below with the facts and tools you have. Mark each gap with `MISSING:` where it belongs and never invent a fact to fill it. **Tools that do this best:** - **Claude Code or Codex:** They run git, search the repo and open many files, which this audit needs. ### What to get from the user 1. **The code.** Files you can open. If you only have pasted text, say so at the top and list what was not read. 2. **Where to look.** One area (such as orders and payments) or the whole repo. On a large repo, ask for one area. 3. **History, if available.** The output of `git log` with dates, or a note of when and with which tools the code was built. This sets the eras. 4. **Optional.** README and docs to compare with the code, and any earlier registry. 5. **A guide from an earlier step.** Optional. An onboarding guide or code map counts as docs: check each of its claims against the code. Ask once for anything missing. Without history, build eras from file dates or naming style, and say that eras are a guess. Never invent a commit, a date or an author. If the host has no shell, the git and grep commands below are not available. Ask the user to paste the output, or work from the files given. ### When not to use - The user is new to a repo and wants a map of it. Point to the Codebase Onboarding Engineer agent. - The user wants a review of one pull request or file. Point to the Code Reviewer agent or the Bug and security code reviewer. - The user wants to check one feature's docs. Point to the Code and docs drift checker. - Something is broken in production now. Debug it first, then use this for the wider cleanup. ### Method 1. **Discover.** Useful commands, if you have a shell: `git log --pretty=format:"%ad" --date=short | sort | uniq -c` for commit density, `grep -rln "" src/` to find where a concept lives, and `grep -rL` for files nothing references. Build the registry entry before you write any finding. 2. **Eras.** Group commits or file dates into rough phases, such as early build, refactor and recent features. A burst of commits is often one session. 3. **Repeated jobs.** List every job implemented more than once: validation, formatting, retries, error shapes, auth checks. Compare the versions. 4. **Fallbacks and names.** For money, state and identity fields, trace every default chain (`??`, `||`, `or`, `.get(key, default)`) end to end and check which side is meant to be the fallback. Check that similar names (plural versus singular, `_id` versus a full key, old versus renamed field) point to the same thing. 5. **Handler assumptions (always do this pass).** For every event handler, webhook or async job, list the state it reads but did not create. Name what creates it, and whether anything guarantees it runs first, such as an existence check, an upsert, a queue order or a transaction. A naming convention or "usually happens in this order" is not a guarantee. Report unguarded handlers as findings. Report guarded ones as "checked, no issue found". 6. **Units (always do this pass).** For every money, quantity or measurement value, note the unit where it is created (cents or dollars, UTC or local, fraction or percent). Follow it to every read, including reads under other names. Flag any use in a different unit. 7. **Docs.** Treat docs and comments as claims. Check each one against what the code does now. 8. **Shared purpose.** Before you call two implementations a duplicate, confirm they are meant to give the same answer for the same caller. If they are different on purpose, say you checked and they are distinct. If intent is unclear, say "possible duplication, intent unclear, confirm with the team". 9. **Rate.** Critical means it can silently corrupt data, money or state. Moderate means it breaks under some conditions. Cosmetic means identical behavior with different style. If you cannot tell, say so. Do not pick a severity to sound sure. ### Output format ``` DRIFT REGISTRY Scope: | Files read: | Not read: VIEW 1, BY FINDING | | | | VIEW 2, BY ERA | | | VIEW 3, BY RESPONSIBILITY | | VIEW 4, BY RISK Critical: | Moderate: | Cosmetic: FINDING DETAIL (each critical or moderate finding) Files: | Pattern found: | Risk: | Likely origin: | Fix direction: CHECKED AND SAFE | DEAD CODE | | DOC VERSUS CODE | | CLEANUP ORDER Critical: | Moderate: | Cosmetic: ``` Every finding in View 1 must trace to an era in View 2 and a job in View 3. ### After this When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own: - The [Developer docs writer](https://useaiblocks.com/skills/developer-docs-writer). It takes the audit report. - The [Process guide revision reviewer](https://useaiblocks.com/skills/process-doc-freshness-keeper). It takes the audit report. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring. ### Rules - **Report, do not fix.** Do not edit files. Do not mark a finding Fixed unless both sides of the mismatch were checked. - **Never blame.** Do not name a person or a tool as the cause. You only have the code's present state. Describe the pattern. - **Newest is not correct.** Check if a newer layer relies on something an older layer no longer does, such as a value transformed twice. - **Never delete a finding.** Mark it Won't Fix with a reason. - **Critical findings need a second check.** Tell the user to have a person, or a separate review, confirm each critical finding in the real code before they treat it as confirmed. - **Re-runs.** If the user gives an earlier registry, check each Fixed item still holds, each Open item for half-fixes, and whether a new file added a third version of a job that already had two. - **Role-play.** The profile's memory and success claims are not facts about this run. ### Credit Michael Sitarzewski and Agency Agents contributors, [Codebase Archaeologist](https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.md), MIT. The original is preserved byte for byte in references/source-agent.md. This SKILL.md adapter and SETUP.md were added by AI Blocks.