void-debug

Diagnose bugs through four phases with failing tests before fixes.

Updated May 29, 2026
One-click install
npx skills add https://github.com/voidcorp-core/void-harness --skill void-debug-voidcorp-core
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: void-debug
Source: https://github.com/voidcorp-core/void-harness/tree/main/packages/core/skills/void-debug
Command: npx skills add https://github.com/voidcorp-core/void-harness --skill void-debug-voidcorp-core

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Bug fixes without a root cause become band-aids that recur months later under a different name. This Skill enforces a disciplined debugging workflow so every fix is backed by a reproducible failing test and a documented root cause. ## Core Features & Use Cases - Four-phase methodology: Investigate (gather evidence), Analyze (narrow with 5 Whys), Hypothesize (testable theory), Implement (failing test first, then fix). - Iron Law enforcement: No fix is accepted without both an identified root cause and a failing test that reproduces the bug, with the test and fix committed separately. - Diagnostic aids: Pattern lookup table for common bug classes (race conditions, nil propagation, state corruption), a 3-strike rule for escalating to structural review, and a blast-radius gate for wide fixes. - Use Case: A production API returns intermittent 500 errors. You reproduce it locally, narrow it via commit bisection and 5 Whys to a missing seed in a migration, write a failing test, commit it, then implement and commit the fix with a root-cause section in the PR body. ## Quick Start Debug this failing checkout test by finding the root cause and writing a reproducing test before any fix.

Frequently Asked Questions about void-debug

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

FAQPage Schema
How do I debug a bug with a failing test first?

Follow the four phases: investigate to gather evidence, analyze to narrow the cause with 5 Whys, hypothesize a testable theory, then write a failing test that reproduces the bug before implementing the fix. Commit the test and the fix separately.

What is a root cause analysis for bug fixes?

Root cause analysis identifies why a bug occurs rather than just fixing its symptom. This Skill requires a 5 Whys chain and a root-cause section in the PR body covering symptom, narrowing steps, fix, and prevention.

How do I debug flaky tests in CI?

Treat flakes as bugs: gather flake conditions, narrow the cause (timing, shared state, randomness), form a hypothesis, then write a failing test that demonstrates the flake before fixing it. Retry-until-green is explicitly rejected.

What should I do when a bug cannot be reproduced locally?

Stop debugging the symptom and add observability first: structured logs, trace IDs, and error boundaries at the suspect surface. Deploy the instrumentation, wait for the next occurrence with real signal, then resume the investigation phase.

When is a bug considered architectural rather than a simple defect?

After three failed hypotheses, or when the same file has been fixed repeatedly, the root cause is likely structural. The fix then becomes a refactor composed with architecture review, kept separate from the bug-close commit.