Codebase Detective — AI skill for Claude Code

Codebase Detective

**Investigate First. Modify Later.**

An AI agent skill that behaves like a software detective instead of a guess-driven code editor. It maps an unfamiliar repository, traces root causes across files, analyses the blast radius of a change, runs the tests that actually exist, and reports what it knows — and what it does not.

Works with opencode, Claude Code, and any agent that can load a `SKILL.md`. Python 3 standard library only — no `pip install`, nothing added to your repo.

# install (opencode, all projects)
git clone https://github.com/marselmarselyt-png/codebase-detective.git \
  ~/.config/opencode/skills/codebase-detective

**Requirements:** Python 3.9+. **31+ automated tests.** **MIT.**

**[Step-by-step install and first run →](docs/getting-started.md)**

---

Why this exists

Coding agents fail in a predictable way: they see a stack trace, form a hypothesis within thirty seconds, and start editing. The edit is usually plausible. Sometimes it is even correct. But nothing in the transcript shows whether the agent understood the system, whether the change breaks something else, or whether the tests were ever run — and the failure is invisible, because a confident summary reads exactly like a correct one.

This skill inverts the order of operations and makes the reasoning auditable.

The six rules

#	Rule
1	No edit before investigation. No code change until a root-cause hypothesis with evidence and an impact assessment exist.
2	Every diagnosis cites file:line. No citation means the claim is labelled a guess.
3	The user's work is protected. Snapshot before editing, verify after, never revert what you did not write.
4	Tests are run or not claimed. Real command, real exit code. "Should pass" is not evidence.
5	Uncertainty is reported. CAUSE NOT FOUND with a hypothesis table is a valid outcome.
6	Risky actions need approval. Deletions, public A