| name | log-debug-issue |
| description | Bug and issue tracking system using markdown files. Record, track, and resolve bugs, errors, and issues encountered during development. Create detailed bug reports with reproduction steps, error messages, root cause analysis, and fixes. Use when debugging code, fixing errors, documenting problems, or maintaining a knowledge base of solutions. |
Debug Issue Logging Skill
This skill provides templates and workflows for systematically tracking bugs, errors, and their resolutions using markdown-based logs.
Quick Start
- Create bug log: Start a new bug log file for your project
- Report a bug: Use the bug report template to document issues
- Investigate: Add investigation notes and findings
- Resolve: Document the fix and root cause
- Review: Maintain a knowledge base of resolved issues
Core Workflow
When a Bug is Encountered
-
Create bug report:
- Use the bug report template from
assets/bug-report-template.md
- Fill in all relevant sections
- Include error messages, stack traces, and screenshots if available
-
Investigate the issue:
- Document reproduction steps
- Add investigation notes as you debug
- Update status as you progress
-
Resolve and document:
- Record the root cause
- Document the fix
- Add testing and verification steps
- Update status to resolved
-
Maintain knowledge base:
- Keep resolved bugs for future reference
- Add to troubleshooting guides
- Share solutions with team
Bug Report Structure
A complete bug report should include:
- Basic Info: ID, title, status, priority, assignee
- Description: What happened vs what was expected
- Reproduction: Steps to reproduce the issue
- Environment: System, software versions, configuration
- Investigation: Debugging process and findings
- Root Cause: Analysis of why the issue occurred
- Fix: Solution implemented
- Verification: How the fix was tested
- Prevention: How to prevent similar issues
Bug Severity Levels
Critical
- System crashes, data loss, security vulnerabilities
- Requires immediate attention
- Blocks core functionality
High
- Major functionality broken
- Workarounds available but cumbersome
- Affects multiple users
Medium
- Minor functionality issues
- Cosmetic or UI problems
- Edge cases not working
Low
- Typos, minor UI inconsistencies
- Enhancement suggestions
- Documentation issues
Investigation Techniques
Error Analysis
- Copy complete error messages and stack traces
- Note timestamps and frequency
- Identify patterns in when errors occur
Reproduction
- Document exact steps to reproduce
- Note any preconditions or specific data needed
- Test on different environments if possible
Debugging
- Add logging to trace execution flow
- Use debuggers to inspect state
- Check logs and monitoring tools
Resolution Documentation
Root Cause Analysis
- Explain why the bug occurred
- Identify underlying issues (not just symptoms)
- Consider design flaws, edge cases, or misunderstandings
Fix Description
- Document code changes made
- Explain why this fix works
- Note any trade-offs or limitations
Testing
- Describe how the fix was tested
- Include regression testing
- Document any new test cases added
Integration with Development
Version Control
- Link bug reports to commit hashes
- Reference pull request numbers
- Include code snippets in bug reports
Project Management
- Sync bug status with task boards
- Update stakeholders on critical issues
- Use bug logs for sprint planning
Team Collaboration
- Assign bugs to appropriate team members
- Add comments and updates
- Share findings in team meetings
Resources
- Bug Report Template: See
assets/bug-report-template.md for a complete template
- Bug Examples: See
references/bug-examples.md for sample bug reports
- Debugging Guide: See
references/debugging-guide.md for investigation techniques
- Common Errors: See
references/common-errors.md for frequently encountered issues
When to Use This Skill
Use this skill when:
- Encountering errors or bugs in code
- Debugging complex issues
- Documenting problems for team reference
- Building a knowledge base of solutions
- Analyzing recurring issues
- Preparing bug reports for issue trackers
- Learning from mistakes to prevent future issues
