investigate-first Skill for Claude: Find the Cause Before Editing

investigate-first makes your coding assistant find and prove the cause of a failure before it edits any code.

Installs: 112.3K; on skills.sh
Stars: 116.7K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

investigate-first tells the assistant to separate what it observed from what it guesses. It traces inputs, state changes, ownership boundaries and failure output. It ranks hypotheses by evidence and by how cheaply each can be disproved, and it does not edit until one cause explains the evidence.

It loads for unknown causes, intermittent behavior and performance regressions. The result is a report of the cause and the proof, with no fix unless your task asks for one. It bundles no scripts, and its SKILL.md names no keys or tools.

Good for

Developers chasing flaky or intermittent failures
Anyone who wants a diagnosis before a fix
Teams tracking down performance regressions

Install investigate-first

Claude Code

Copy this prompt.

Install the investigate-first skill in Claude Code. Run this command:

npx skills add https://github.com/juliusbrussee/caveman --skill investigate-first

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.

Key facts

Author: Julius Brussee (repo owner juliusbrussee)
Repository: juliusbrussee/caveman, folder skills/investigate-first
Installs on skills.sh: 112,250 (as of 2026-11-02)
Repo stars: 116,702 (whole repository, as of 2026-11-02)
License: Apache-2.0
Last repo commit: 2026-11-01
Files in the skill folder: 2 files: SKILL.md and agents/openai.yaml
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Keep the symptom apart from the guessed cause
Separates the observed symptom from the inferred cause.
Observed vs inferred
Follow inputs, state changes and failure output
Traces inputs, state transitions, ownership boundaries and failure output.
Read · Trace the path
Order by evidence and cheap tests that could disprove them
Ranks hypotheses by evidence and by how cheaply each can be falsified.
Rank hypotheses
No code changes until one cause fits the evidence
Does not edit until one credible mechanism explains the evidence.
No edits yet
Stop when the cause or the exact blocker is named
Stops exploring once the evidence is enough to name the cause or the exact blocker.
Know when to stop
Report cause and proof; no fix unless authorized
Reports the cause and proof, and makes no fix unless the task authorizes implementation.
Report

From the official docs

Permissions

Low risk

It is told to investigate and report, and to make no fix unless your task authorizes one, so the risk is low.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It reads first and fixes only if you ask
The skill says to make no fix unless your task authorizes one. If you do authorize a fix, review the diff.

Questions

What does the investigate-first skill do?

It makes the assistant investigate before it fixes. It gathers evidence, ranks the possible causes, names one cause with proof, and edits nothing unless you asked for a fix.

How do I install investigate-first in Claude Code, the Claude app or Codex?

Use the install box at the top of the page and pick your client. The SKILL.md bundles no scripts and lists no other requirements. The folder also includes an agents/openai.yaml file. The README says your agent picks these work patterns up when a task fits, so you do not need to call it by name.

Does investigate-first need an API key or an account?

No. The SKILL.md asks for no key, login or tool. It is plain instructions for the assistant, and it bundles no scripts.

Is investigate-first safe to use?

It is a short instruction file and bundles no scripts. What it changes is how the assistant behaves when it edits your project, so review the diff and keep your usual git and test setup. The permissions section below lists what to watch.

How is investigate-first different from surgical-patch?

investigate-first ends with a diagnosis and does not fix anything unless you authorize it. surgical-patch starts from a known failure and changes the narrowest layer that owns the bug. Use investigate-first when you do not yet know why something fails.

Information

updated Nov 2, 2026

Repository: juliusbrussee/caveman
Folder: skills/investigate-first

juliusbrussee/caveman skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

investigate-first SKILL.md · github.com
caveman README · github.com
investigate-first openai.yaml · github.com
surgical-patch SKILL.md · github.com