debug

Guide bug investigation with reproduction, hypothesis ranking, and fix validation.

1|Updated Jan 27, 2026
One-click install
npx skills add https://github.com/Joaovsales/coding-agent-workflow --skill debug-joaovsales
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug
Source: https://github.com/Joaovsales/coding-agent-workflow/tree/main/.agents/skills/debug
Command: npx skills add https://github.com/Joaovsales/coding-agent-workflow --skill debug-joaovsales

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps software teams systematically diagnose and fix bugs by applying rigorous root-cause analysis, structured reproduction, and documented memory to prevent regressions.

Core Features & Use Cases

  • Pre-Flight Diagnostics: Align context by reviewing memory, memory lessons, and bug register to surface known patterns.
  • Root-Cause Prelude (Phase 0.5): Generate Top-3 candidates and choose the most plausible cause using disconfirming evidence.
  • Phase 1 — Reproduce & Isolate: Write minimal reproduction steps and isolate the failing path, then form 2-3 hypotheses with evidence levels.
  • Phase 2 — Fix & Validate: Apply root-cause fixes with minimal changes and verify via a structured loop of tests.
  • Phase 3 — Verify with Loop: Run iterative tests until all pass, capturing regressions and confirmations.
  • Phase 4 — Register & Learn: Update bug register and capture debugging lessons for future issues.
  • Lessons & Process: Use the provided artifacts to improve future debugging.

Quick Start

Describe the bug concisely and run the /debug command to initiate the investigation workflow.

Frequently Asked Questions about debug

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

FAQPage Schema
How do I perform root-cause analysis for a flaky test or runtime bug?

Root-cause analysis for a flaky test or runtime bug requires gathering logs and memory references to form hypotheses, rank evidence, and write minimal reproduction steps to isolate the failing path. This approach systematically narrows down the exact trigger.

What is the best way to reproduce and isolate a user-reported bug?

To reproduce and isolate a user-reported bug, you should write minimal reproduction steps, isolate the failing path, and form 2-3 hypotheses with assigned evidence levels. This structured isolation prevents speculative fixes and focuses on verified triggers.

How do I rank evidence and hypotheses during bug investigation?

Rank evidence and hypotheses during bug investigation by generating Top-3 root-cause candidates and choosing the most plausible cause using disconfirming evidence. Reviewing memory and known bug register patterns helps align context and rank the evidence accurately.

Can I use this debugging workflow for performance regressions in my software projects?

Yes, you can use this debugging workflow for performance regressions in your software projects. The structured reproduction and root-cause analysis process applies to runtime issues, flaky tests, and performance regressions by guiding evidence gathering and controlled testing.

How do I prevent regressions when validating a root-cause fix?

To prevent regressions when validating a root-cause fix, apply minimal changes and verify via an iterative loop of tests. Running tests until all pass captures both regressions and confirmations before you update the bug register.