repo-debugging-ledger

Repo Debugging Ledger

Use this skill as a lightweight overlay on normal debugging. Its job is to prevent loops and untested assumptions.

Start With A Repro Signal

Create the smallest useful pass/fail loop:

• unit/integration test,
• CLI command,
• HTTP request,
• browser script,
• fixture replay,
• log assertion,
• repeated flake trigger.

If no loop exists, state the best available signal and what artifact would make it deterministic.

Hypothesis Ledger

Before editing, write or mentally maintain 3-5 ranked hypotheses:

H1:
Prediction:
Probe:
Result:
Status: open / supported / falsified

Probe one variable at a time. Prefer evidence that distinguishes between hypotheses.

Checked-Location Ledger

Track what has already been inspected:

Checked:
- file/function/command:
  evidence:
  conclusion:

Do not reopen the same file, rerun the same broad search, or repeat the same command unless a phase change makes it newly relevant: new failing signal, new stack trace, changed code, or a narrowed hypothesis.

Search And Instrumentation

• Use rg and targeted file reads first.
• Search for exact symbols, error text, config keys, route names, and call sites before broad terms.
• Tag temporary logs with a unique marker such as [DEBUG-7b3c].
• Remove temporary instrumentation before finalizing.
• If a likely area is exhausted, broaden to a different subsystem instead of cycling through the same files.

Fix Discipline

• Add or identify a regression check before the fix when a reasonable seam exists.
• Keep the fix scoped to the supported hypothesis.
• Re-run the original repro signal after the fix.
• Run the project’s normal checks before finalizing, or explain the blocker.

Final Report

Include:

• root cause or best-supported cause,
• files changed,
• verification run,
• residual risks or missing test seam.