systematic-debugging

Files (9)

• SKILL.md
• advanced-debugging-governance.md
• condition-based-waiting-example.ts
• condition-based-waiting.md
• defense-in-depth.md
• feedback-loop-construction.md
• find-polluter.sh
• root-cause-claim-contract.md
• root-cause-tracing.md

SKILL.md (first lines)

# 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.

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.
Apply the same causal-sufficiency standard to every bug. Trace relevant
influences and justify exclusions; resolve repair-changing unknowns before
retaining a solution. Experiments may precede closure. Evidence gaps, not
apparent size or risk, determine investigation depth.

## Quick bug lane

For an evidenced local, 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. This reduces readback, not
the causal coverage or evidence standard.
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**.
   For task distortion, follow source → understanding → expression → execution
   → delivery to the first evidenced change in meaning. This identifies where
   divergence is observed, not a proven root; reuse sufficient current evidence.
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: 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. This bounded reminder is not a behavior matrix, relationship graph,
referential-integrity proof, or exhaustive discovery claim. It adds no artifact,
TDD risk signal, or regression scope; the existing TDD route owner and

From GanyuanRan/Aegis, MIT.

More from GanyuanRan/Aegis