Skills juliusbrussee caveman Caveman
investigate-first
- Use it when:
- Something fails and the cause is unclear: an intermittent bug, an odd behavior or a performance regression.
- It does:
- Separates what was observed from what's guessed, and weighs each explanation by its evidence and by how cheap it is to test.
- You get:
- The cause and the evidence for it, or the exact blocker, with no code changed unless the task asks for a fix.
- Unlike surgical-patch:
- That one goes on to fix the bug; this one stops at the diagnosis.
- Runs:
- On its own, whenever the agent sees a task that fits; it's a short list of rules, not a step-by-step guide.
Skill 11 of 16 in the Caveman bundle, after caveman-explore and before lean-build.
TL;DR
The agent touches no product code until the problem is understood. It keeps the observed symptom apart from the cause it suspects, and traces inputs, state changes, which part of the code is responsible for what, and the failure output. It ranks its hypotheses by the evidence for them and by how cheaply each could be ruled out, and won't edit anything until one explanation accounts for all the evidence. It stops exploring once it can name the cause or the exact thing blocking it, and reports the cause with its proof.
Summarizes the skill at bad48a0.
npx skills add https://github.com/juliusbrussee/caveman --skill investigate-first skills.sh pageSource on GitHubAll skills from juliusbrussee/caveman
More weekly downloads than 92% of skills
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 13,144 |
| Sep 28 | 10,916 |
| Oct 5 | 10,142 |
| Oct 12 | 8,346 |
| Oct 19 | 7,199 |
| Oct 26 | 7,582 |
| Nov 2 | 7,204 |
| Nov 9 | 6,879 |
More downloads than 89% of skills
More stars than 93% of repos
Newer than 93% of skills
| Category |
Find root causes, review code and test what you built. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills. |
|---|---|
| Type |
A multi-step process the agent follows: interview, debug, run a TDD loop, review. |
| Effect |
Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code. |
| Needs |
Instructions only. Works in any agent that supports skills. |
| Publisher |
Everyone else. Unverified vendor claims default to community. |
| Topics |
SKILL.md
From juliusbrussee/caveman at bad48a0. Checked daily, last changed Oct 20, 2026.
Frontmatter
name: investigate-first
description: Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.Investigate first
Gather evidence before changing product code.
- Separate observed symptom from inferred cause.
- Trace inputs, state transitions, ownership boundaries, and failure output.
- Rank hypotheses by evidence and cheap falsification value.
- Do not edit until one credible mechanism explains evidence.
- Stop exploration when evidence is sufficient to name cause or exact blocker.
Report cause and proof. Make no fix unless task authorizes implementation.