bug-investigation

Diagnose software defects through reproducible feedback loops, ranked hypotheses, and TDD-based fixes.

1|Updated Apr 3, 2026
One-click install
npx skills add https://github.com/TierOne-Studio/spa-velocity --skill bug-investigation-tierone-studio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bug-investigation
Source: https://github.com/TierOne-Studio/spa-velocity/tree/main/.ruler/skills/bug-investigation
Command: npx skills add https://github.com/TierOne-Studio/spa-velocity --skill bug-investigation-tierone-studio

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a bug report, failing test, CI failure, or production incident lands on your plate, ad-hoc guessing wastes hours and often patches symptoms instead of causes. This Skill enforces a disciplined root-cause workflow: build a fast deterministic reproduction loop, generate ranked falsifiable hypotheses, fix via TDD, and add regression coverage so the bug class never returns. ## Core Features & Use Cases - Feedback-loop construction: Ranked strategies for building a pass/fail signal, from failing tests and curl scripts to headless browsers, bisection harnesses, and differential loops. - Systematic diagnosis: Non-deterministic bug categorization (timing, environment, state, random), layer localization decision trees, and git bisect automation for regressions. - Hypothesis-driven fixing: Generate 3-5 ranked falsifiable hypotheses, instrument one variable at a time, then fix via TDD with broader regression tests and a post-mortem for production incidents. - Use Case: A CI pipeline fails intermittently on a React frontend. The Skill guides you to classify the flakiness as timing-dependent, widen the race window with artificial delays, build a deterministic failing test, bisect to the introducing commit, and land a guarded fix. ## Quick Start Investigate this failing test and find the root cause before proposing any fix.

Frequently Asked Questions about bug-investigation

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

FAQPage Schema
How do I find the root cause of a bug instead of patching symptoms?

Build a fast deterministic pass/fail loop that reproduces the bug, then generate 3-5 ranked falsifiable hypotheses and test them one variable at a time. You have the root cause only when you can answer why the bug appeared now.

How to debug a flaky test that fails intermittently?

Classify the flakiness first as timing-dependent, environment-dependent, state-dependent, or truly random. Then raise the reproduction rate by looping the trigger, adding artificial delays, running under concurrency, or isolating leaked state between tests.

How do I use git bisect to find which commit introduced a bug?

Mark the current HEAD as bad and a known-good commit as good, then run git bisect run with your failing test command. The test exit code drives the search, finding the introducing commit in roughly log2(N) runs.

What should I do when I cannot reproduce a bug locally?

Stop and say so explicitly rather than guessing. Ask for environment access, captured artifacts like HAR files or log dumps, or permission to add temporary instrumentation before forming hypotheses.

When should a bug fix be escalated instead of fixed autonomously?

Escalate when missing permissions or artifacts block reproduction, when the fix requires an ambiguous behavior decision, or when multiple plausible root causes cannot be narrowed without external information.