structural-investigating

Diagnose defects and unknowns through time-boxed, hypothesis-driven investigation workflows.

Updated May 27, 2026

Search Tags:#debugging #troubleshooting #root cause analysis #flaky tests #hypothesis testing #incident investigation #spike

Ready to run

npx skills add https://github.com/ybaspinar/agent-work-skills --skill structural-investigating-ybaspinar

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: structural-investigating
Source: https://github.com/ybaspinar/agent-work-skills/tree/main/skills/structural-investigating
Command: npx skills add https://github.com/ybaspinar/agent-work-skills --skill structural-investigating-ybaspinar

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging sessions often drift without a clear question, fixes get tested against flaky reproductions, and spike code leaks into production. This Skill structures investigations so every inquiry ends with a diagnosis, a failing test, or a documented decision. ## Core Features & Use Cases - Bounded Inquiry: Forces a single named question, a time box, and a pre-decided fallback if the box expires. - Falsifiable Hypotheses: Requires a disprovable theory and bisection steps that halve the search space before probing. - Reproduction Discipline: Prioritizes deterministic reproduction, or pins variables and measures a failure rate when determinism is impossible. - Use Case: A flaky integration test fails 1 in 20 CI runs. Use this Skill to pin controlled inputs, measure the failure rate, bisect hypotheses using traces and commit diffs, and hand off a diagnosis with a red test instead of an unproven fix. ## Quick Start Use the structural-investigating skill to investigate why the nightly job intermittently fails and produce a diagnosis with a failing test.

Frequently Asked Questions about structural-investigating

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

FAQPage Schema

How do I debug a flaky test that fails intermittently?▼

Pin controlled inputs and measure an actual failure rate instead of chasing a deterministic repro. Form one falsifiable hypothesis, bisect the search space with targeted probes, and treat silence after a fix as no proof of resolution.

How to structure a technical spike or investigation?▼

Name one question, set a time box, and decide upfront what happens if the box expires. End with a diagnosis plus a failing test or decision record, and throw spike code away unless you are ready to harden and own it.

What should an incident investigation produce as output?▼

An investigation should produce a diagnosis, a red test or spike finding, a list of ruled-out causes, and follow-up actions. Recording what was ruled out prevents the next person from rerunning the same dig.

When should I add debug logging during an investigation?▼

Cash in existing observability such as traces, logs, and commit or config diffs before adding new probes. If you add debug logging, scope it narrowly and remove it afterward rather than leaving broad instrumentation in place.

Why do investigations fail to find root causes?▼

Common failure modes include starting without a named question or clock, changing multiple layers at once, and trusting wall-clock ordering or narratives over artifacts. Use causal ids, traces, and diffs as evidence instead.