debug-loop

Diagnose failed loopgen runs and map outcomes to concrete spec or workspace fixes.

1|1|Updated Jun 27, 2026
One-click install
npx skills add https://github.com/ShortStackEngineer/loop-generator --skill debug-loop-shortstackengineer
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-loop
Source: https://github.com/ShortStackEngineer/loop-generator/tree/main/.claude/skills/debug-loop
Command: npx skills add https://github.com/ShortStackEngineer/loop-generator --skill debug-loop-shortstackengineer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? When a loopgen run fails, stalls, hits max iterations, or comes back green but suspicious, it is hard to tell whether the agent, the spec, or the workspace is at fault. This Skill reads the run report, classifies the failure by its outcome field, and pinpoints the root cause without spending more agent budget. ## Core Features & Use Cases - Outcome-based triage: Classifies runs by outcome (max-iterations, preflight-failed, error, baseline-vacuous, spec-tampered, aborted, vacuous-success) and maps each to a likely cause and fix. - Budget-free reproduction: Confirms root causes with lint and by running the failing check command by hand, avoiding costly agent re-runs. - False-positive detection: Treats green runs with warnings (no files changed, agent did not complete) as suspect and verifies the checks actually test the requirement. - Use Case: A loop run exhausts its 5 iterations with the same check failing. The Skill reads the last iteration's evaluator feedback and agent stopReason, reproduces the failing command in the resolved workspace, and identifies a wrong test command in the evaluator options. ## Quick Start Ask the assistant to diagnose why your .loop.yaml run failed, providing the terminal output or the --report JSON file.

Frequently Asked Questions about debug-loop

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a loopgen run that hit max iterations?

Read the last iteration in the report: check which evaluator never passed and its feedback, the agent stopReason (completed, max_turns, or error), and whether files changed. Then run the failing check command by hand in the resolved workspace to confirm the root cause.

Why did my loop run pass but change no files?

A green run with a 'changed no files' warning means the checks are likely vacuous and pass on untouched code. Confirm by running the check manually on a clean checkout; it should fail before any work. Fix the check so it stays red until the requirement is met.

What does the baseline-vacuous outcome mean in loopgen?

baseline-vacuous means the checks already passed before the agent ran, so they do not test the new requirement. Repair the check so it is red until the requirement is satisfied, following the RED-for-the-right-reason contract.

Can I diagnose a failed loop run without spending agent budget?

Yes. Run loopgen lint with --strict for static config issues, then execute the failing evaluator command manually in the resolved workspace to see the real exit code and output. Only re-run the full loop after these cheap checks pass.

Why does my loop run fail with preflight-failed or error outcomes?

preflight-failed indicates environment or config problems like a wrong workspace.dir or missing local binary, listed in the reason bullets. An error outcome usually means a typo in driver.uses or evaluator uses; verify names with loopgen list.