code-debugging
lingzhi227/agent-research-skills
Debug experiment code with structured error analysis and retry logic.
What is code-debugging?
Systematically diagnoses and fixes errors in experiment code by categorizing issues (syntax, runtime, logic), analyzing root causes, and applying targeted fixes with reflection. Use when experiment code fails or produces incorrect results.
- Categorizes errors into six types (SyntaxError, ImportError, RuntimeError, TimeoutError, OutputError, LogicError) with severity levels
- Analyzes root causes by reading tracebacks and identifying exact lines, variables, and common patterns (device mismatch, shape mismatch, missing normalization)
- Applies fix strategies tailored to error type: direct fixes for syntax/import, retry loops for runtime, reflection for logic errors, optimization for timeouts
- Implements retry logic with up to 4-5 fix attempts before changing approach
- Reflects on fixes to explain why errors occurred and prevent recurring issues
- Verifies fixes don't introduce new errors and maintains error history
How to install code-debugging
npx skills add https://github.com/lingzhi227/agent-research-skills --skill code-debuggingHow to use code-debugging
- 1.Provide the error message, stderr output, or code file with issues to the skill
- 2.Optionally include the code that produced the error for context
- 3.The skill will categorize the error and identify its severity level
- 4.Review the root cause analysis and proposed fix strategy
- 5.Execute the fix and verify it resolves the issue without introducing new errors
- 6.Review the reflection summary to understand the error pattern and avoid it in future code
Use cases
- Fixing shape mismatches or device mismatches in tensor operations during model training
- Debugging 0% accuracy by checking accuracy calculation and data pipeline issues
- Resolving infinite loops or timeout errors by reducing dataset size or adding early stopping
- Correcting off-by-one indexing errors and missing data normalization steps
- Addressing ImportError and missing module dependencies in experiment scripts
- Machine learning researchers and engineers debugging training code
- Data scientists troubleshooting experiment failures
- Anyone iterating on experimental code with systematic error analysis
code-debugging FAQ
Six categories: SyntaxError (low severity), ImportError (low), RuntimeError (medium), TimeoutError (medium), OutputError (medium), and LogicError (high severity).
Up to 4-5 fix attempts before changing approach. For syntax/import errors it attempts a direct fix once; for runtime errors it retries up to 4 times; for logic errors it reflects and considers alternative methods.
After 4-5 attempts, the skill will suggest changing approach or regenerating the code from scratch rather than continuing to patch the same issue.
For logic errors, the skill first checks the accuracy calculation itself, then traces through the data pipeline to identify where correct values are lost or transformed incorrectly.
Device mismatch (CPU vs GPU tensors), shape mismatch in matrix operations, missing data normalization, off-by-one indexing errors, and incorrect loss functions for the task type.
Full instructions (SKILL.md)
Source of truth, from lingzhi227/agent-research-skills.
name: code-debugging description: Debug experiment code with structured error analysis. Categorize errors, apply targeted fixes with retry logic, and use reflection to prevent recurring issues. Use when experiment code fails or produces incorrect results. argument-hint: [error-or-code]
Code Debugging
Systematically debug experiment code with structured error categorization and fix strategies.
Input
$0— Error message, stderr output, or code file with issues$1— Optional: the code that produced the error
References
- Debug patterns and state machine:
~/.claude/skills/code-debugging/references/debug-patterns.md
Workflow
Step 1: Categorize the Error
| Category | Examples | Severity |
|---|---|---|
| SyntaxError | Invalid syntax, indentation | Low |
| ImportError | Missing module, wrong name | Low |
| RuntimeError | Division by zero, shape mismatch | Medium |
| TimeoutError | Infinite loop, too slow | Medium |
| OutputError | Missing files, wrong format | Medium |
| LogicError | Wrong results, 0% accuracy | High |
Step 2: Analyze Root Cause
- Read the error traceback (last 1500 chars if truncated)
- Identify the exact line and variable causing the error
- Check for common patterns:
- Device mismatch (CPU vs GPU tensors)
- Shape mismatch in matrix operations
- Missing data normalization
- Off-by-one errors in indexing
- Incorrect loss function for task type
Step 3: Apply Fix Strategy
For syntax/import errors: Direct fix, single attempt For runtime errors: Fix and rerun, up to 4 retries For logic errors: Reflect on approach, consider alternative methods For timeout: Reduce dataset size, optimize bottleneck, add early stopping
Step 4: Reflect and Prevent
After fixing:
- Explain why the error occurred
- Identify which lines caused it
- Describe the fix line-by-line
- Note patterns to avoid in future code
Fix Strategy State Machine
Stage 0 (first attempt) → repost code as fresh
Stage 1 (second attempt) → repost or leave depending on severity
Stage 2 (third attempt) → regenerate from scratch if still failing
Rules
- Prefer minimal targeted edits over full rewrites
- Maximum 4-5 fix attempts before changing approach
- Always truncate long error outputs to last 1500 characters
- After fixing, verify the fix doesn't introduce new errors
- Keep error history to avoid repeating the same mistakes
- If 0% accuracy: check accuracy calculation first, then check data pipeline
Related Skills
- Upstream: experiment-code
- See also: paper-to-code, data-analysis
Related skills
More from lingzhi227/agent-research-skills and the wider catalog.
data-analysis
Generate rigorous statistical analysis code with multi-round review and proper uncertainty reporting.
deep-research
Conduct systematic 6-phase academic literature reviews with structured output and synthesis.
excalidraw-skill
Programmatic canvas toolkit for creating and refining Excalidraw diagrams with real-time sync and element-level control.
experiment-code
Generate and iteratively improve ML experiment code for research papers with training pipelines, debugging, and result optimization.
experiment-design
Design structured, progressive experiment plans for research papers with staged baselines, hyperparameter sweeps, and ablation studies.
figure-generation
Generate publication-quality scientific figures with matplotlib/seaborn using query expansion, code generation, and VLM visual feedback.