Hire an AI codebase history researcher

Everything it can hand back

Your task sets the actual outputs. The specialist picks the methods that cover them.

• 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

How it does the job well

• 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.
• Never report a duplicate implementation as automatically wrong — some duplication is intentional (e.g. deliberately decoupled services). Confirm the two implementations are supposed to agree before flagging disagreement as a bug.
• Never guess at intent you can't verify — if you can't tell from the code and history whether a mismatch is a bug or a deliberate divergence, say so explicitly rather than assigning a severity you can't support.

Mistakes it avoids

• Losing commitments buried in long notes.
• Mixing confirmed facts with guesses about other people's plans.
• Adding process when a short checklist would do.

What a good result looks like

An example, not your task: A project grew over months with several AI coding tools, and you do not trust that the parts agree.

• 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.

How the work is checked

• Every action has an owner and a date, or is marked as missing one.
• Each item points to the note or message it came from.
• The output fits where it will be used, such as one screen or one page.
• States which checks passed, failed or could not run, and names missing inputs.

These checks have not been run against a model yet. Your AI uses them to check its own work.

Capabilities

• Rebuild the eras. It groups commits or file dates into rough phases, so each mismatch can be explained as a file that never got migrated.
• List repeated jobs. It finds every job done more than once, such as validation or retries, and compares the versions.
• Trace fallbacks and names. It follows default-value chains on key fields, and checks that similar names point to the same thing.
• Check handler assumptions. For each event or job handler, it lists the state it reads and checks if anything guarantees that state exists first.
• Trace units. It follows each money or quantity value from where it is made to every place it is read, and checks the unit is the same.
• Rate and register. It confirms shared purpose before flagging duplicates, sorts findings as critical, moderate or cosmetic, and fills the four views.

How the role works

1. Checks your task, context and available tools.
2. Picks the methods needed and prepares a work plan.
3. Carries out supported tasks, with each method's limits and review gates.
4. Checks the real deliverables and corrects supported faults.
5. Hands back files, evidence and unresolved gaps.

Your specialist's working setup

Download the base specialist without a task form or account. README.md and SETUP.md explain how to use the folder. SOUL.md defines its scope. INTAKE.md asks missing questions inside your AI. PLAYBOOK.md, SKILLS.md, BEST_PRACTICES.md, CHECKS.md and HANDOFF.md guide the work and its checked deliverables.

Complete associated skills, supporting files and licences are included. Choose only the methods needed for the actual task. Keep context, working files and accepted feedback in your AI project.

Use this specialist through MCP or the API

Call prepare_specialist with role_id specialized-codebase-archaeologist only. No task is required to load it. Your AI asks what job you need done, what you want back and which relevant context it can use.

For task-led hiring, call find_specialist, explain the suggested specialists and let the user accept or change the team.

Complete ZIP: Download base specialist. API: GET /api/v1/specialists/specialized-codebase-archaeologist/pack. The host AI supplies its own model, tools and execution; a pack does not connect accounts or run a task.

Inputs and helpful context

The specialist starts from the task brief. Only active methods require their inputs.

For the primary method, when used

• 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)

Helpful context (optional)

• A list of the tools and rough dates that touched the code, so eras are easier to name.
• A short note on which values are money or stock, so the unit check starts in the right place.

Tools and access

• Claude Code or Codex: They run git, search the repo and open many files, which this audit needs.

Functions and deliverables

• 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.
  • 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
  Source: Michael Sitarzewski and Agency Agents contributors.
• Metric mismatch tracer: Share two reports and their calculations. Compare the gap, trace where they differ and document a fix or unresolved cause.
  • The size of the gap
  • The step where the two diverge
  • The root cause by type
  • A corrected query or tolerance note
  • A completed reconciliation report
  Source: Nimrod Fisher.
• Shopify duplicate customer record finder: Find Shopify customer records with matching contact details or names. Get likely duplicate groups to review; records stay separate until you resolve them.
  • Groups of likely duplicate customers
  • Order counts and spend for each record
  • Plain or JSON output
  • A list ready to merge by hand
  Source: 40rty AI.
• Research paper and code note writer: Share a paper, repo or messy notes. Get claims, methods and evidence sorted into a clear research folder.
  • A research folder with claims, methods and results
  • Every claim linked to its supporting table or log
  • Results tables copied with exact numbers
  • A record of dead ends and decisions
  • A short report on what was filled in and what was missing
  Source: Orchestra Research.
• me.md builder: Answer a few questions, or let your AI use what it remembers. Get one private file that tells any AI who you are.
  • One me.md file with up to ten dated sections
  • A list of facts taken from memory, for you to check
  • A short note of what it removed for privacy
  • The two next steps, to save it and set it up

Tasks you can use it for

• 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.

Limits to check before starting

• 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.

Best way to use this role

Give it one clear outcome, the actual files and a definition of done. Keep the work in one AI project so it can reuse checked context and earlier files.

• 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.
• Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.
• 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.
• Read the critical findings first. For each one, open both files and check that the mismatch is real.
• Fix one finding at a time, in both files. Then rerun with the registry attached to see that it stayed fixed.
• Hand confirmed findings to a person or tool that can edit the code. This agent does not change files.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/specialized-codebase-archaeologist for its role instructions and pinned sources.

This is a prepared AI role. No task has run. Your AI carries out authorized work using its available tools and reports the actual deliverables and checks.