# Systematic Debugging

Use when encountering a bug, test failure, or unexpected behavior, before proposing fixes

- Repository: https://github.com/GanyuanRan/Aegis (1408 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-25
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add GanyuanRan/Aegis --skill systematic-debugging -g -a claude-code -y`
Codex: `npx skills add GanyuanRan/Aegis --skill systematic-debugging -g -a codex -y`
Cursor: `npx skills add GanyuanRan/Aegis --skill systematic-debugging -g -a cursor -y`
Gemini CLI: `npx skills add GanyuanRan/Aegis --skill systematic-debugging -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add GanyuanRan/Aegis`

## Description

Use when encountering a bug, test failure, or unexpected behavior, before proposing fixes

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Execute

Bug, failure, or unexpected behavior:

1. **Isolate**, read error, reproduce, inspect the diff, and drill upward through diagnostic layers:
   L1 symptom → L2 logic → L3 system → L4 architecture → L5 cross-system
   contract → L6 platform → L7 spec gap. Layers are observation altitudes,
   not one causal chain; the causal shape at the stop altitude is classified
   explicitly before any root claim. Stop only when causal proof accounts
   for the recurrence generator or reaches a T-class boundary.
2. **Identify owner**, compare working behavior, trace the bad value, locate the
   canonical owner, and treat duplicate owners as a finding.
3. **Decide before editing**, Before fixing, run Patch-Shape Triage and Ripple Signal Triage when shared logic,
   contracts, fallbacks, adapters, producer/consumer seams, or source-of-truth
   boundaries are involved. Surface Change Necessity for any new source-code
   path or non-trivial source edit. Run Minimality Check for a new branch,
   fallback, adapter, owner, or compatibility path, and Pre-Edit Complexity
   Check for an overloaded owner or complexity growth. After Change Necessity
   selects `code-change` and before the first repair edit, own the TDD Route for
   the repair slice per `test-driven-development` (`off` default; `strict` on
   behavior/bugfix/shared/contract/persistence/permission/migration risk).
4. **Prove**, test one hypothesis with the smallest reproduction or
   verification. A failing test first is required only by a recorded
   `TDD Route: strict`; with `TDD Mode: off`, do not require a failing test or
   RED/GREEN cycle. Three failed fixes means stop and question architecture.
5. **Repair and close**, fix minimally at the canonical owner, verify in
   proportion to risk, review architecture, and close both repair and
   retirement tracks. If a symptom remains or shifts, reopen the causal model;
   do not assume it is a separate defect.

The rest: https://github.com/GanyuanRan/Aegis/blob/HEAD/skills/systematic-debugging/SKILL.md