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
- which goes on to fix the bug, this 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 8 of 12 in the Caveman bundle · Before it: cavecrew · After it: lean-build
TLDR
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-firstskills.sh page · Source on GitHub · All skills from juliusbrussee/caveman
- Installs
- 61,966 on skills.sh, Sep 21, 2026
- Repo stars
- 106,976 juliusbrussee/caveman
- First seen
- Aug 11, 2026 on skills.sh
Weekly values
| Week to | Installs |
|---|---|
| Aug 3 | 0 |
| Aug 10 | 0 |
| Aug 17 | 6,309 |
| Aug 24 | 8,930 |
| Aug 31 | 9,022 |
| Sep 7 | 11,129 |
| Sep 14 | 12,577 |
| Sep 21 | 13,222 |
| 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.