systematic-debugging

Document kernel debugging investigations through Problem, Root Cause, Solution, and Evidence phases.

7|Updated Nov 21, 2015

Search Tags:#debugging #documentation #troubleshooting #bug fix #software development #root cause analysis #kernel

Ready to run

npx skills add https://github.com/ryanbreen/breenix --skill systematic-debugging-ryanbreen

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: systematic-debugging
Source: https://github.com/ryanbreen/breenix/tree/main/breenix-systematic-debugging
Command: npx skills add https://github.com/ryanbreen/breenix --skill systematic-debugging-ryanbreen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Kernel bugs are notoriously difficult to diagnose and often recur if not properly understood and documented. This Skill provides a structured, document-driven debugging workflow (Problem → Root Cause → Solution → Evidence) to ensure complex issues are thoroughly investigated, fixed, and their lessons preserved.

Core Features & Use Cases

Structured Problem Analysis: Clearly define symptoms and observable failures.
Root Cause Investigation: Systematically narrow down the source of the bug with logging and state analysis.
Documented Solutions: Implement and explain fixes, providing concrete evidence of resolution.
Use Case: You're facing an intermittent kernel panic that's hard to reproduce. Use this Skill to document the problem, systematically investigate the call stack and memory state, propose a solution, and provide before/after logs as evidence, ensuring the fix is robust and understood by the team.

Quick Start

Start by defining the problem:

Problem Summary

Direct userspace execution was failing with a double fault at `int 0x80`

Symptoms

- Userspace processes boot successfully

- Calling int 0x80 triggers double fault

- Error occurs during Ring 3 → Ring 0 transition

Frequently Asked Questions about systematic-debugging

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

FAQPage Schema

How do I systematically debug complex kernel issues?▼

Systematic kernel debugging uses a structured four-phase workflow: define the Problem with observable symptoms, investigate Root Cause through logging and state analysis, implement a documented Solution, and provide Evidence via diagnostic logs. This approach ensures thorough investigation and reproducible fixes that prevent recurrence.

What's the best way to document kernel bug fixes for team understanding?▼

Document kernel bug fixes using a Problem→Root Cause→Solution→Evidence template. This preserves lessons learned, enables other team members to understand the fix rationale, and creates a reference for similar issues, reducing debugging time for recurring failures.

How do I investigate intermittent kernel panics that are hard to reproduce?▼

Intermittent kernel panics require systematic documentation of symptoms, call stack analysis, memory state inspection, and structured logging. Capture before/after diagnostic logs as evidence, then propose and validate the fix using this documented workflow to ensure robustness.

Can I use this debugging workflow for CI investigation and architectural issues?▼

Yes, the document-driven debugging workflow applies to kernel bugs, architectural issues, recurring failures, and CI investigation problems. The four-phase structure works across contexts where reproducibility and root-cause understanding are critical.

Why is structured documentation important when troubleshooting kernel bugs?▼

Kernel bugs often recur without proper documentation of the root cause and investigation process. Structured documentation ensures the fix is understood by the team, prevents duplicate debugging efforts, and creates a knowledge base for similar failures.