Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot

investigate-first — Claude Code skill: diagnose before editing

The skill keeps the agent in diagnosis mode: gather evidence, rank hypotheses, name the cause. Only then does it touch code.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add JuliusBrussee/caveman --skill investigate-first -a claude-code
Open on GitHub

What investigate-first does

Most agent debugging starts with a guess and a patch. This one starts with evidence. The agent keeps the observed symptom apart from its inferred cause, then walks the input path, state transitions, module ownership boundaries and the failure output itself.

Hypotheses get ranked by how much evidence backs them and how cheaply each can be falsified. Exploration stops once a single mechanism explains everything you saw, or once the exact blocker is named — no drifting around the codebase afterwards. The report is cause plus proof. No fix unless the task authorizes implementation, which is the part that saves you from a confident edit in the wrong file.

Install is one command: npx skills add JuliusBrussee/caveman --skill investigate-first -a codex, and you swap the -a flag for Cursor, Copilot, Gemini CLI or OpenCode. You get a single SKILL.md with the protocol, nothing else to wire up. Worth it on repos large enough that a stack trace stops pointing at a file. For a typo in one line, a plain prompt is quicker.

What it helps with

  • pin down an intermittently failing test
  • trace a performance regression back to a dependency bump
  • separate the symptom you can see from the cause the agent assumes
  • get a written cause and proof before anyone edits product code
  • cut off an open-ended investigation once the blocker is named

Example prompts for the agent

  • Find out why `checkout.spec.ts` fails only on CI. Don't change any code yet.
  • Investigate the latency jump on `/api/orders` and show the evidence behind each hypothesis
  • We keep seeing `ECONNRESET` in the logs — run the investigation and falsify the cheap hypotheses first

How to install investigate-first

1Skills CLI (Vercel)

npx skills add JuliusBrussee/caveman --skill investigate-first -a claude-code

2Manually: put the files in place

~/.claude/skills/investigate-first/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/investigate-first/

From the same set22

The whole set →
caveman JuliusBrussee Cuts filler and polite greetings from agent responses while keeping technical facts and code exact. Stays active until turned off. Claude Code CX Codex Cursor +1 591,500installs caveman-commit JuliusBrussee Generates terse Conventional Commits messages focused strictly on intent. Ideal for keeping git history clean without boilerplate or AI signatures. Claude Code CX Codex Cursor +1 414,700installs caveman-review JuliusBrussee Generates terse, single-line code review comments with exact line numbers, problems, and fixes. Eliminates conversational filler in pull request reviews. Claude Code CX Codex Cursor +1 410,700installs caveman-compress JuliusBrussee Rewrites CLAUDE.md and todo files into terse caveman-speak so the model reads fewer input tokens. The source gets overwritten; a readable backup stays out of tree. Claude Code CX Codex Cursor +1 410,300installs caveman-help JuliusBrussee A quick reference for Caveman modes and commands in Claude Code and other supported hosts. Use it when you need to control response style or find related skills. Claude Code CX Codex Cursor +1 401,800installs cavecrew JuliusBrussee cavecrew delegates code searches, small edits, and diff reviews to three subagents. Use it when keeping the main agent's context lean matters. Claude Code CX Codex Cursor +1 357,900installs caveman-stats JuliusBrussee Displays recorded output and cache-read tokens for Claude Code sessions or points to host native usage stats. Useful for tracking raw token consumption. Claude Code CX Codex Cursor +1 356,700installs caveman-explore JuliusBrussee A read-only skill locates relevant files and line ranges in a repository. Use it for cold-start orientation or broad searches. Claude Code CX Codex Cursor +1 106,500installs

Similar

ponytail-audit DietrichGebert It audits a repository and ranks bugs, risks, and redundant code in a one-shot report. Use it when you need a review without code changes. Claude Code CX Codex Cursor +1 44,800installs improve-codebase-architecture Matt Pocock This skill scans a codebase for architectural friction, then builds a visual HTML report with refactoring candidates. Use it before a deeper architecture review. Claude Code 1,163,035installs tdd Matt Pocock Guides the red-green TDD loop: ensures tests are written first, keep them at public interfaces, and avoid coupling to implementation details. Claude Code 1,141,062installs triage Matt Pocock This skill moves issues and external PRs through triage states, verification, and agent briefs. It fits maintainers managing an issue queue. Claude Code 990,453installs codebase-design Matt Pocock This skill helps design modules with small interfaces and hidden complexity. Use it when refactoring code, choosing a seam, or making tests easier to write. Claude Code 850,344installs code-review Matt Pocock Reviews changes from a chosen reference point against repository standards and the originating spec. Use it for a branch, PR, or work in progress. Claude Code 789,521installs implement Matt Pocock Implements work from a specification or tickets, following a test-driven flow and ending with review and a commit. Use it when a coding task needs a defined delivery routine. Claude Code 774,700installs

Questions about investigate-first

How do I install investigate-first in Claude Code?

Run npx skills add JuliusBrussee/caveman --skill investigate-first -a claude-code. The skill lands at ~/.claude/skills/investigate-first/SKILL.md.

What does investigate-first do?

It sets the order of work for a failure: evidence first, hypotheses ranked, cause named. The agent makes no fix unless the task authorizes implementation.

Which failures is it meant for?

Unknown causes, intermittent behaviour and performance regressions. The cases where you cannot point at a line yet.

Source text

SKILL.md · Apache-2.0 
---
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.

© JuliusBrussee · Apache-2.0 · JuliusBrussee/caveman

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor