systematic-debugging
Use when encountering a bug, test failure, or unexpected behavior, before proposing fixes
GanyuanRan · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add GanyuanRan/Aegis --skill systematic-debugging技能说明
name: systematic-debugging description: "Use when encountering a bug, test failure, or unexpected behavior, before proposing fixes"
Execute
Bug, failure, or unexpected behavior:
- 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.
- Identify owner — compare working behavior, trace the bad value, locate the canonical owner, and treat duplicate owners as a finding.
- 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-changeand before the first repair edit, own the TDD Route for the repair slice:offskips automatic TDD;autoselectsstricton any behavior, bugfix, shared/core, contract, persistence, permission, migration, producer/consumer, or meaningful regression signal.lightrequires every tiny/low-risk/single-owner/no-behavior-change condition; missing explicit user TDD wording is never auto-light evidence. - Prove — test one hypothesis with the smallest reproduction or
verification. A failing test first is required only by a recorded
TDD Route: strict; withTDD Mode: off, do not require a failing test or RED/GREEN cycle. Three failed fixes means stop and question architecture. - Repair and close — fix minimally at the canonical owner, verify in proportion to risk, review architecture, and close both repair and retirement tracks. If any symptom remains, stop and diagnose it separately.
Done: confidence ≥ B, causal status matches recurrence evidence or an external terminal, tracks explicit, no H signal, and required D evidence passes.
Core invariant
Find root cause and fix the bug class at its canonical owner. A minimal fix is not the smallest textual diff; it is the smallest sufficient owner-level repair.
Quick bug lane
For a low-risk, reproducible, single-owner bug with no patch-shape signal, keep
the readback compact: Symptom, Reproduction, Root Cause, Change Necessity, Fix Boundary, and Verification. Skip the causal card only when
the causal-proof owner's Quick Exit Proof passes.
Quick bug lane must surface Change Necessity before source edits. One sentence
may cover the user-visible need, no-change/non-code option, why code must
change, minimum boundary, and an explicit decision token such as
Decision: code-change. If shared logic, a contract, fallback, duplicate
owner, consumer patch, or cross-module behavior appears, leave this lane.
Aegis Visibility names the evidence/owner/patch-shape/verification effect.
Pass root cause, avoided misfix, boundary, evidence, complexity, and risk to
verification-before-completion; no separate receipt.
Diagnose before repair
- Read the complete error/stack and record inputs, environment, versions, and success criteria.
- Reproduce consistently. If reproduction is not stable, read
feedback-loop-construction.mdonly when evidence shows intermittent or timing-dependent reproduction and build a bounded automated loop. - Inspect recent changes and compare a working example. Code is evidence; if
authority, glossary, code, and tests disagree, compose
establishing-project-contextrather than silently redefining a term. - Instrument component boundaries, then trace the bad value toward its source.
Read
root-cause-tracing.mdonly when the observed bad value is several calls or components downstream from its origin. - State one hypothesis and falsify it with one-variable evidence. Do not stack
speculative fixes. End each loop with
Goal | DeeperCause | Evidence | Risk/Unknown | Decision.
Canonical-owner and patch-shape gate
Before editing, continue upward unless evidence proves the local site is the canonical owner when the candidate is any of these signals:
- keyword, phrase, regex, negation-word list, or sample-text exception;
- local guard, extra conditional,
try/catch, early return, or one-off branch; - fallback, adapter, compatibility branch, prompt branch, or legacy path expansion;
- consumer/caller/readiness/presentation-layer patch;
- downstream logic re-parses raw text or re-infers action/state while typed intent, normalized state, contract, or another source-of-truth exists;
- artifact/download/export/readback/cache patch without producer/owner proof.
PatchShape:
CanonicalOwner:
UpwardDrillSignal:
Decision: fix owner | continue investigation | escalate
A locally green test does not erase triage. Before unplanned repair, compare invariant, owner, patch shape, and topology; a renamed carrier is not a new direction.
When a repair may reinterpret or retire existing semantics, responsibility, contract, or relationship, name the behavior to preserve, highest-risk counterexample, and material unknown. For each known explicit anchor or upstream/downstream reference, state its role and disposition: preserve, rebind to the canonical owner, retire with reason, or reject because of conflict. Leave unresolved relationships unknown; do not re-infer them downstream. Bind role before value and retire invalid responsibility, not evidenced carrier capability. Identifiers and selectors are examples, not the trigger. This bounded
阅读完整来源 ↗