debug-loop
Use when debugging a failing test or runtime error with hypothesis-driven investigation, autonomous command validation, and systematic root cause elimination.
Best use case
debug-loop is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when debugging a failing test or runtime error with hypothesis-driven investigation, autonomous command validation, and systematic root cause elimination.
Teams using debug-loop should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debug-loop/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debug-loop Compares
| Feature / Agent | debug-loop | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when debugging a failing test or runtime error with hypothesis-driven investigation, autonomous command validation, and systematic root cause elimination.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
SKILL.md Source
# 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 ```bash 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
Related Skills
qe-debug-loop
Hypothesis-driven autonomous debugging with real command validation
iterative-loop
Runs continuous AI iteration loops that repeat build-test-fix cycles until success criteria are met. Use when building features requiring test-driven refinement, implementing tasks with clear pass/fail criteria, or automating iterative improvement workflows.
qe-iterative-loop
Runs autonomous red-green-refactor loops to fix failing tests, reach coverage targets, and satisfy quality gates. Use when tests need to pass, coverage thresholds must be met, quality gates require compliance, or flaky tests need stabilization.
qe-visual-testing-advanced
Advanced visual regression testing with pixel-perfect comparison, AI-powered diff analysis, responsive design validation, and cross-browser visual consistency. Use when detecting UI regressions, validating designs, or ensuring visual consistency.
qe-verification-quality
Comprehensive truth scoring, code quality verification, and automatic rollback system with 0.95 accuracy threshold for ensuring high-quality agent outputs and codebase reliability.
qe-testability-scoring
AI-powered testability assessment using 10 principles of intrinsic testability with Playwright and optional Vibium integration. Evaluates web applications against Observability, Controllability, Algorithmic Simplicity, Transparency, Stability, Explainability, Unbugginess, Smallness, Decomposability, and Similarity. Use when assessing software testability, evaluating test readiness, identifying testability improvements, or generating testability reports.
qe-test-reporting-analytics
Advanced test reporting, quality dashboards, predictive analytics, trend analysis, and executive reporting for QE metrics. Use when communicating quality status, tracking trends, or making data-driven decisions.
qe-test-idea-rewriting
Transform passive 'Verify X' test descriptions into active, observable test actions. Use when test ideas lack specificity, use vague language, or fail quality validation. Converts to action-verb format for clearer, more testable descriptions.
qe-test-environment-management
Test environment provisioning, infrastructure as code for testing, Docker/Kubernetes for test environments, service virtualization, and cost optimization. Use when managing test infrastructure, ensuring environment parity, or optimizing testing costs.
qe-test-design-techniques
Systematic test design with boundary value analysis, equivalence partitioning, decision tables, state transition testing, and combinatorial testing. Use when designing comprehensive test cases, reducing redundant tests, or ensuring systematic coverage.
qe-test-data-management
Strategic test data generation, management, and privacy compliance. Use when creating test data, handling PII, ensuring GDPR/CCPA compliance, or scaling data generation for realistic testing scenarios.
qe-test-automation-strategy
Design and implement effective test automation with proper pyramid, patterns, and CI/CD integration. Use when building automation frameworks or improving test efficiency.