Systematic Debugging

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 177240a262fe · 18 Oct 2026Report an issue or request a re-scan

• PublisherGanyuanRan GitHub userOwner of the repository this skill is read from
• Source folderGanyuanRan/Aegis/skills/systematic-debuggingThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict177240a262feA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

---
name: systematic-debugging
description: "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 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

For UI/interaction defects, compose `ui-ux-governance` for relevant state and
recovery rules at the user-visible seam. Keep reproduction/root-cause ownership
here; a proposed manual check is not executed evidence.

1. Read the complete error/stack and record inputs, environment, versions, and
   success criteria. Reproduce the user's failed outcome on the correct object,
   through final delivery; successful parsing or green internal checks may hide
   the failure. Verify the repaired behavior and a relevant neighboring case,
   not a hardcoded example. Read-only diagnosis does not authorize repair.
2. Reproduce consistently. If unstable, read
   `feedback-loop-construction.md` **only when evidence shows intermittent or
   timing-dependent reproduction** and build a bounded loop. Shrink the repro
   to load-bearing elements as the test input, never the fix scope: still drill
   upward; test at the correct seam.
3. Inspect recent changes and compare a working example. Code is evidence; if
   authority, glossary, code, and tests disagree, compose
   `establishing-project-context` rather than silently redefining a term.
4. Instrument component boundaries, then trace the bad value toward its source.
   Read `root-cause-tracing.md` **only when the observed bad value is several
   calls or components downstream from its origin**.
5. 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.

```text
PatchShape:
CanonicalOwner:
UpwardDrillSignal:
Decision: fix owner | continue investigation | escalate
```

A locally green test does not erase triage; 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: pr

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/GanyuanRan/Aegis
git -C Aegis checkout 177240a262fe

Works in

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source 177240a262fe

Questions about Systematic Debugging

• github.com/GanyuanRan/Aegis/tree/main/skills/systematic-debuggin — the audited source at commit 177240a262fe and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology