Skills

Systematic Debugging

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

Install

npx skills add GanyuanRan/Aegis --skill systematic-debugging -g -a claude-code -y
Repository
GanyuanRan/Aegis1.4k
Category
Testing
Updated
11d ago
License
MIT
Context cost
Mediumabout 2,944 tokens
Runs scripts
Yes, review before use

What it does

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

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.
Read the whole SKILL.md on GitHub

More in Testing