log-debug-issue

The log-debug-issue skill provides a systematic framework for documenting the software debugging lifecycle within the VRP-Toolkit project. It is designed for developers, researchers, and maintainers who need to track complex issues, unexpected behavior, and recurring bugs in stochastic optimization models or ALNS heuristics. By enforcing a consistent logging format in .claude/DEBUG_LOG.md, the agent creates a searchable knowledge base that helps prevent regression, accelerates root cause analysis, and simplifies long-term maintenance.

• Capture structured issue metadata including dates, environmental context (OS, Python version, package versions), and precise reproduction steps for inconsistent ALNS results or stochastic failures.
• Document the iterative investigation process, recording initial hypotheses, failed experiments, and diagnostic tests, which provides visibility into the thought process during difficult debugging sessions.
• Formalize solution implementation by tracking the root cause, implemented fix, temporary workarounds, and long-term prevention strategies such as unit tests or architectural refactors.
• Maintain a 'Common Patterns & Solutions' section to facilitate knowledge transfer, allowing team members to quickly reference previously resolved issues like import errors, indexing bugs, or dependency conflicts.
• Bridge the gap between debugging and project management by integrating with task boards, ensuring that unresolved bugs in the log are properly tracked as blockers or active tasks in CLAUDE.md.
• Cross-reference debugging efforts with version control by recommending the inclusion of issue IDs in Git commit messages for traceability.

Users should trigger this skill whenever an anomaly occurs, such as unexpected output from the ALNS algorithm, numerical instability in continuous approximation models, or failures in the PDPTW test suite. The skill requires the user to input the problem description, symptom details, and findings from their investigation. The expected output is a structured markdown entry in the repository's debug log that adheres to the established templates, ensuring that the documentation is standardized across all project modules. When debugging, keep in mind that maintaining accurate 'Lessons Learned' sections is critical for future optimization of the VRP framework. Constraints include ensuring that entries are added to the dedicated path .claude/DEBUG_LOG.md to maintain repository cleanliness and adherence to the project's development workflow.