skills.rest
huangbaixun
huangbaixunCOMMUNITY
Explore all skills by this author →
GitHub

harness:systematic-debugging

Guide structured root-cause debugging with hypothesis testing and incident documentation.

3|1|Updated Apr 5, 2026
Search Tags:#debugging#root cause analysis#test failures#hypothesis testing#incident reporting#integration troubleshooting#ADR invalidation
One-click install
npx skills add https://github.com/huangbaixun/harness-engineering --skill harness-systematic-debugging
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: harness:systematic-debugging
Source: https://github.com/huangbaixun/harness-engineering/tree/main/skills/systematic-debugging
Command: npx skills add https://github.com/huangbaixun/harness-engineering --skill harness-systematic-debugging

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Prevents wasted effort and recurring regressions by forcing disciplined root-cause investigation before any code or configuration changes.

Core Features & Use Cases

  • Root-cause-first debugging: Requires completing a structured investigation before proposing fixes, emphasizing evidence over guesses.
  • Phase-based workflow: Guides Root Cause Investigation, Pattern Analysis, Hypothesis and Testing, and then Implementation with validation.
  • Multi-component evidence gathering: Directs you to instrument boundaries (CI→build→signing, API→service→DB, etc.) to pinpoint which layer breaks.
  • ADR and incident documentation guardrails: Enforces incident note conventions and mandates ADR invalidation updates when assumptions are broken.

Quick Start

Use the skill when a test fails or behavior is unexpected, and tell the AI: “Debug this failure using harness:systematic-debugging—start with root-cause investigation, then produce an incident note under docs/incidents with symptom, reproduction, root cause, and fix (or escalation).”

Frequently Asked Questions about harness:systematic-debugging

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

FAQPage Schema
How do I find the root cause of a test failure before proposing code fixes?▼

Use systematic debugging to investigate unexpected behavior by instrumenting component boundaries (like CI to build or API to DB) to pinpoint the exact failing layer. This enforces evidence collection across multi-component workflows before proposing fixes.

What is the best way to debug integration failures across multiple components?▼

Systematic debugging directs you to instrument boundaries across multi-component workflows, such as CI, build, signing, API, service, and database layers, to pinpoint which integration boundary actually breaks before applying fixes.

How do I document an incident when a regression is identified?▼

Document an incident by generating a structured note under your docs directory containing the symptom, reproduction steps, root cause, and applied fix or escalation. This enforces consistent incident reporting conventions for regressions.

When should I update or invalidate an ADR during incident troubleshooting?▼

You must invalidate or update an Architecture Decision Record (ADR) when systematic hypothesis testing disproves the assumptions held in the original architecture. This is a mandatory guardrail when investigating unexpected system behavior.

What are the limitations of guessing fixes instead of doing root cause analysis?▼

Guessing fixes without root cause analysis often leads to wasted effort and recurring regressions because the underlying failing boundary is never identified. Systematic debugging overcomes this by enforcing evidence-based hypothesis testing.

Related Skills

Explore More Software Engineering Skills→
DethonDethon
3

systematic-debugging

Diagnose software bugs through a four-phase root-cause investigation workflow.

Community
Advanced
csackridercsackrider

agent-learn

Capture post-feature and post-incident learnings into PROJECT.md, ADRs, and Tech Specs.

Community
Advanced
moirai-internalmoirai-internal

SGLang Bisect CI Regression

Bisect SGLang CI logs to identify regression-introducing commits.

Official
Advanced
xxihxxih
1

systematic-debugging

Identify root causes of bugs through a four-stage systematic process.

Community
Intermediate