agentleFS
Sign inStart free
proffesor-for-testingproffesor-for-testing/agentic-qe/.claude/skills/debug-loop/SKILL.md

debug-loop

Skill515 starsChanged 22 days agoMITView on GitHub

Use when debugging a failing test or runtime error with hypothesis-driven investigation, autonomous command validation, and systematic root cause elimination.

We split this skill into the rules it gives an agent

14 rules. 0 are common, 13 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Run the exact command that shows the bug.

    line 19
  2. Distinctive:

    If the bug cannot be reproduced, stop and explain what was tried.

    line 21
  3. Very specific:

    Run a REAL command to test it (e.g., sqlite3 [db path] '.tables' then SELECT COUNT(*) FROM [table])

    line 26
  4. Distinctive:

    If rejected, form the next hypothesis based on what you learned

    line 28
  5. Distinctive:

    Always check both v2 and v3 SQLite tables when data issues are suspected

    line 33
  6. Distinctive:

    Check dependency versions (e.g., sqlite3 vs better-sqlite3)

    line 34
  7. Distinctive:

    Check for hardcoded values that may have been missed

    line 35
  8. Distinctive:

    Before applying, grep for ALL instances of the problematic pattern across the entire codebase.

    line 43
  9. Distinctive:

    Run the SAME reproduction command from Phase 1.

    line 46
  10. Distinctive:

    Run the full test suite. If tests fail, fix them before committing.

    line 54
  11. Distinctive:

    NEVER guess or simulate output — always run real commands

    line 58
  12. Distinctive:

    NEVER make code changes before confirming root cause

    line 59
  13. Distinctive:

    Always check for the pattern across the entire codebase, not just one file

    line 60
  14. Distinctive:

    If blocked after 5 hypotheses, stop and ask the user for guidance

    line 61

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Debug Loop

Autonomous hypothesis-driven debugging against real data. No guessing, no simulating.

Arguments

  • <symptom> — Description of the bug or unexpected behavior. If omitted, prompt the user.

Phases

Phase 1 — Reproduce

Run the exact command that shows the bug. Capture and display the REAL output. Confirm the bug is visible.

If the bug cannot be reproduced, stop and explain what was tried.

Phase 2 — Hypothesize and Test (up to 5 iterations)

For each iteration:

  1. State a specific hypothesis (e.g., "the query targets v2 tables but data is in v3 tables")
  2. Run a REAL command to test it (e.g., sqlite3 [db path] '.tables' then SELECT COUNT(*) FROM [table])
  3. Record whether the hypothesis was confirmed or rejected
  4. If rejected, form the next hypothesis based on what you learned

Do NOT make code changes until you have a confirmed root cause.

Important checks:

  • Always check both v2 and v3 SQLite tables when data issues are suspected
  • Check dependency versions (e.g., sqlite3 vs better-sqlite3)
  • Check for hardcoded values that may have been missed

Phase 3 — Fix

Make the minimal targeted fix. Explain:

  • What the root cause was
  • What you're changing and why
  • What the blast radius is (which other code paths are affected)

Before applying, grep for ALL instances of the problematic pattern across the entire codebase.

Phase 4 — Verify

Run the SAME reproduction command from Phase 1. The output must now show correct values. If it doesn't, go back to Phase 2.

Show before/after output comparison.

Phase 5 — Regression

npm test

Run the full test suite. If tests fail, fix them before committing.

Rules

  • NEVER guess or simulate output — always run real commands
  • NEVER make code changes before confirming root cause
  • Always check for the pattern across the entire codebase, not just one file
  • If blocked after 5 hypotheses, stop and ask the user for guidance

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free