skills.rest
hhenrichsen
hhenrichsenCOMMUNITY
Explore all skills by this author →
Website𝕏@hhenrichsen_GitHub

caveman--investigate-first

Diagnoses ambiguous failures by ranking evidence-based hypotheses before editing code.

Updated Dec 3, 2025
Search Tags:#debugging#troubleshooting#root cause analysis#diagnostics#hypothesis testing#failure investigation
One-click install
npx skills add https://github.com/hhenrichsen/dots --skill caveman-investigate-first-hhenrichsen
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman--investigate-first
Source: https://github.com/hhenrichsen/dots/tree/main/dot_skills/caveman/investigate-first
Command: npx skills add https://github.com/hhenrichsen/dots --skill caveman-investigate-first-hhenrichsen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineers often jump to fixing code before understanding the actual cause of a failure, leading to wasted effort and regressions. This Skill enforces an evidence-first diagnostic workflow for ambiguous bugs, intermittent behavior, and performance regressions. ## Core Features & Use Cases - Symptom-Cause Separation: Distinguishes observed symptoms from inferred causes to avoid chasing false leads. - Evidence-Ranked Hypotheses: Traces inputs, state transitions, and ownership boundaries, then ranks hypotheses by evidence and falsification cost. - Use Case: When a production service intermittently times out, use this Skill to gather logs and trace failure output until one credible mechanism explains the evidence, before any code change is made. ## Quick Start Use investigate-first to diagnose this intermittent test failure and report the root cause with proof before proposing any edits.

Frequently Asked Questions about caveman--investigate-first

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose a bug with an unknown root cause?▼

Start by separating the observed symptom from the inferred cause, then trace inputs, state transitions, and failure output. Rank hypotheses by evidence strength and how cheaply each can be falsified before editing any code.

How to investigate intermittent test failures before fixing them?▼

Gather evidence from failure output and ownership boundaries first, then rank candidate mechanisms by falsification value. Do not edit code until one credible mechanism explains all observed evidence.

When should I stop investigating a performance regression?▼

Stop exploration when the evidence is sufficient to name the cause or identify the exact blocker. Continuing past that point wastes effort without improving diagnostic confidence.

Does this investigation approach make code changes automatically?▼

No. The workflow reports the cause and supporting proof only, and makes no fix unless the task explicitly authorizes implementation. Diagnosis and remediation are kept as separate steps.

What are the limitations of hypothesis-based debugging?▼

Hypothesis ranking depends on the quality of available evidence such as logs and traces. If failure output is missing or ownership boundaries are unclear, the investigation may stall at an exact blocker rather than a named cause.

Related Skills

Explore More Software Engineering Skills→
rahmanayonrahmanayon

investigate

Plan root-cause investigations across investigate, analyze, hypothesize, and implement phases.

Community
Advanced
tanveerriaztanveerriaz
1

bug-root-cause-analysis

Diagnose bugs through a reproduce, isolate, fix, and validate workflow.

Community
Intermediate
prefactordevprefactordev
3

instrument-existing-agent-with-prefactor-sdk

Instrument existing agents with Prefactor to trace run, LLM, and tool boundaries.

Official
Advanced
hey-konghey-kong

sglang-bisect-ci-regression

Extract failure signatures and bisect CI regression commit ranges in SGLang workflows.

Community
Advanced