# Repo Debugging Ledger

> Debug repositories with a hypothesis ledger, checked locations, and loop-breaking discipline. Use when tests fail, CI fails, behavior regresses, local tooling errors, flaky bugs appear, or an investigation risks repeated searches, repeated commands, circular hypotheses, or unverified fixes.

- Skill: `markoblogo/repo-debugging-ledger` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add markoblogo/repo-debugging-ledger`
- Raw SKILL.md: https://api.skillmd.com/api/skills/markoblogo/repo-debugging-ledger/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: markoblogo (https://skillmd.com/u/markoblogo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/markoblogo/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:

```text
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:

```text
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.