debugging

This skill provides a structured framework for systematic debugging and troubleshooting within software repositories. Designed for developers and AI agents, it enforces a disciplined approach to identifying, isolating, and resolving defects. By integrating these best practices, teams can minimize the time spent on root cause analysis and reduce the probability of regression. This skill is intended for use in environments where consistent code quality and standardized diagnostic procedures are critical for project maintainability. It serves as an essential component for projects managed by the ai-rules tool, ensuring that AI agents follow project-specific error-handling conventions and logging strategies.

• Systematic diagnostic workflow including log verification, reproduction, isolation, and verification.

• Best practices for utilizing binary search and divide-and-conquer methods to narrow down complex issues.

• Guidelines for effective logging, including where and how to insert temporary instrumentation for flow tracing.

• Methods for tracking code evolution and reviewing commit history to identify recently introduced regressions.

• Ensure all application logs and stack traces are captured before beginning the analysis.

• The primary input for this skill is the repository context, while the output is a refined, reproducible defect report or a suggested fix.

• When implementing these rules, always ensure the environment remains in a clean state to prevent secondary errors from masking the root cause.

• Always prioritize creating a reliable reproduction step before applying any code changes to avoid speculative fixes.

• Use this skill in conjunction with automated testing suites to verify that bug fixes do not inadvertently break existing functionality.

• Applicable to a wide range of programming languages and frameworks, provided the repository environment supports standard logging and git-based version control.