debug

Guide engineers through a four-phase evidence-driven debugging workflow for flaky failures.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/cjennings/rulesets --skill debug-cjennings
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug
Source: https://github.com/cjennings/rulesets/tree/main/debug
Command: npx skills add https://github.com/cjennings/rulesets --skill debug-cjennings

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Investigate a bug or test failure methodically through four phases — understand the symptom, isolate variables, form and test hypotheses, then fix at the root. The workflow emphasizes collecting evidence before proposing fixes, rejects shotgun debugging, and escalates to architectural investigation after three failed fix attempts.

Core Features & Use Cases

  • Four-phase, phase-ordered debugging workflow: Understand the symptom, identify the root cause, verify hypotheses with evidence, and implement a minimal, well-documented fix.
  • Evidence-centric analysis: reproduction steps, logs, traces, and data-flow review are captured to support conclusions.
  • Root-cause hypothesis and escalation: encourages explicit hypotheses, validation, and escalation when fixes stagnate.
  • Safeguards against guessing: formal process prevents ad-hoc fixes and ensures traceability.
  • Companion practices: aligns with start-work, root-cause-trace, and five-whys for cross-checking insights.
  • Practical applicability: suitable for unclear or inconsistent failure modes in tests or production.

Quick Start

Describe the symptom and then work through Phase 1 to Phase 4 in order to gather evidence and identify the root cause before proposing a fix.

Frequently Asked Questions about debug

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

FAQPage Schema
How do I debug flaky test failures with inconsistent logs?

To debug flaky test failures with inconsistent logs, follow a structured, evidence-driven workflow that enforces four sequential phases: understand the symptom, identify the root cause, verify the hypothesis with failing tests, and fix with minimal changes.

What is the best way to find the root cause of intermittent production bugs?

The best way to find the root cause of intermittent production bugs is applying a phase-ordered debugging workflow that captures reproduction steps, logs, and traces as evidence to validate root-cause hypotheses before implementing fixes.

How do I stop shotgun debugging when fixing software failures?

To stop shotgun debugging when fixing software failures, use an evidence-centric analysis process that requires explicit root-cause hypotheses and validation through failing tests, rejecting ad-hoc fixes to ensure traceability.

When should I escalate an incident during root-cause analysis?

You should escalate an incident during root-cause analysis after three failed fix attempts, triggering an architectural investigation to resolve the stagnation and document remaining evidence.

Does this debugging workflow support cross-checking insights with other methods?

Yes, this debugging workflow supports cross-checking insights by aligning with companion practices like start-work, root-cause-trace, and five-whys analysis methodologies.

Step by step guide to systematically debug unclear software failures?

To systematically debug unclear software failures, describe the symptom, then work through Phase 1 to Phase 4 in order: understand the symptom, identify the root cause, verify hypotheses with evidence, and implement a minimal, well-documented fix.