investigate-first

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

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/bittlinkm/claude-setup --skill investigate-first-bittlinkm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: investigate-first
Source: https://github.com/bittlinkm/claude-setup/tree/main/skills/investigate-first
Command: npx skills add https://github.com/bittlinkm/claude-setup --skill investigate-first-bittlinkm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Engineers often jump straight to editing code when facing ambiguous bugs, intermittent behavior, or performance regressions, which leads to wrong fixes and wasted effort. This Skill enforces an evidence-first diagnostic workflow so the root cause is identified before any change is made. ## Core Features & Use Cases - Evidence-Gathering Discipline: Separates observed symptoms from inferred causes and traces inputs, state transitions, ownership boundaries, and failure output. - Hypothesis Ranking: Ranks candidate causes by supporting evidence and cheap falsification value, stopping exploration once one credible mechanism explains the evidence. - Use Case: When a production service intermittently times out, use this Skill to trace the failure path, rank hypotheses such as connection pool exhaustion versus downstream latency, and report the proven cause before authorizing any fix. ## Quick Start Use investigate-first to diagnose this intermittent test failure and report the root cause with evidence before proposing any code changes.

Frequently Asked Questions about 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 and cheap falsification value, and stop once one credible mechanism explains the evidence.

How to investigate intermittent test failures before fixing them?

Gather evidence about when and where the failure occurs, including ownership boundaries and failure output, before editing anything. Rank candidate causes by falsification cost and confirm one mechanism explains all observations before proposing a fix.

When should I use evidence-based debugging instead of editing code directly?

Use it for ambiguous failures, intermittent behavior, and performance regressions where the cause is unknown. Direct editing is only appropriate once a credible mechanism explains the evidence or the task explicitly authorizes implementation.

What are the limitations of hypothesis-based debugging?

It can slow down trivial fixes where the cause is already obvious, and it depends on the availability of observable evidence such as logs and failure output. It reports the cause but makes no fix unless the task authorizes implementation.