Initial commit

skills/error-troubleshooter/assets/debug-notes-template.md

@@ -0,0 +1,396 @@
+# Debug Session: [Brief Error Summary]
+
+**Date**: [YYYY-MM-DD]
+**Status**: [Active/Resolved/Blocked]
+**Investigator**: Claude Error Troubleshooter
+
+---
+
+## Error Information
+
+### Error Message
+```
+[Paste full error message here, including stack trace if available]
+```
+
+### Context
+- **Command/Tool Executed**: `[command or tool that failed]`
+- **What Was Being Attempted**: [Brief description of the goal]
+- **When It Failed**: [e.g., during build, at runtime, on specific input]
+
+### Initial Observations
+- [Key observation 1]
+- [Key observation 2]
+- [Key observation 3]
+
+---
+
+## Environment Information
+
+### System
+- **OS**: [e.g., Ubuntu 22.04, macOS 13.1, Windows 11]
+- **Architecture**: [e.g., x86_64, ARM64]
+- **Shell**: [e.g., bash, zsh, PowerShell]
+
+### Runtime
+- **Language/Runtime**: [e.g., Python 3.11.0, Node.js 18.12.0]
+- **Package Manager**: [e.g., pip 22.3.1, npm 8.19.2]
+- **Virtual Environment**: [e.g., active venv at /path/to/venv, none]
+
+### Dependencies (Relevant Packages)
+```
+[package-1]==1.2.3
+[package-2]==4.5.6
+```
+
+### Configuration (Sanitized)
+```
+[Relevant configuration settings, with sensitive data redacted]
+```
+
+---
+
+## Error Template
+
+**Extracted Template** (for searching):
+```
+[Error template with variables removed - see error-template-patterns.md]
+```
+
+**Search Queries Used**:
+- `[query 1]`
+- `[query 2]`
+- `[query 3]`
+
+---
+
+## Research Findings
+
+### Source 1: [Stack Overflow / GitHub Issue / Docs / etc.]
+**URL**: [link]
+
+**Summary**: [Brief summary of relevant information]
+
+**Applicability**: [High/Medium/Low - how relevant is this to our case?]
+
+**Key Quotes/Code**:
+```
+[Relevant code snippet or quote]
+```
+
+---
+
+### Source 2: [Title]
+**URL**: [link]
+
+**Summary**: [Brief summary]
+
+**Applicability**: [High/Medium/Low]
+
+**Key Quotes/Code**:
+```
+[Relevant information]
+```
+
+---
+
+### Source 3: [Title]
+**URL**: [link]
+
+**Summary**: [Brief summary]
+
+**Applicability**: [High/Medium/Low]
+
+---
+
+## Theories
+
+### Theory 1: [Concise Description]
+**Likelihood**: [High/Medium/Low]
+
+**Evidence Supporting**:
+- [Evidence 1]
+- [Evidence 2]
+
+**Evidence Against**:
+- [Counter-evidence 1]
+- [Counter-evidence 2]
+
+**How to Test**:
+```bash
+[Command or approach to verify this theory]
+```
+
+**Expected Outcome if Correct**:
+[What would we observe if this theory is correct?]
+
+**Expected Outcome if Incorrect**:
+[What would we observe if this theory is wrong?]
+
+**Status**: [Pending/Testing/Confirmed/Rejected]
+
+---
+
+### Theory 2: [Concise Description]
+**Likelihood**: [High/Medium/Low]
+
+**Evidence Supporting**:
+- [Evidence 1]
+- [Evidence 2]
+
+**Evidence Against**:
+- [Counter-evidence 1]
+
+**How to Test**:
+```bash
+[Command or approach]
+```
+
+**Expected Outcome if Correct**:
+[Description]
+
+**Expected Outcome if Incorrect**:
+[Description]
+
+**Status**: [Pending/Testing/Confirmed/Rejected]
+
+---
+
+### Theory 3: [Concise Description]
+**Likelihood**: [High/Medium/Low]
+
+**Evidence Supporting**:
+- [Evidence]
+
+**Evidence Against**:
+- [Counter-evidence]
+
+**How to Test**:
+```bash
+[Command]
+```
+
+**Expected Outcome if Correct**:
+[Description]
+
+**Expected Outcome if Incorrect**:
+[Description]
+
+**Status**: [Pending/Testing/Confirmed/Rejected]
+
+---
+
+## Tests Conducted
+
+### Test 1: [Brief Test Description]
+**Date/Time**: [When was this test run]
+
+**Theory Being Tested**: [Which theory or theories does this test address?]
+
+**Test Procedure**:
+```bash
+[Exact commands or steps taken]
+```
+
+**Expected Result**:
+[What we expected to happen]
+
+**Actual Result**:
+```
+[What actually happened - output, errors, observations]
+```
+
+**Analysis**:
+[What does this result tell us? Does it support or reject any theories?]
+
+**Conclusion**:
+- [Theory X]: [Supported/Rejected/Inconclusive]
+- [New information learned]
+
+---
+
+### Test 2: [Brief Test Description]
+**Date/Time**: [When]
+
+**Theory Being Tested**: [Theory name]
+
+**Test Procedure**:
+```bash
+[Commands]
+```
+
+**Expected Result**:
+[Description]
+
+**Actual Result**:
+```
+[Output]
+```
+
+**Analysis**:
+[Interpretation]
+
+**Conclusion**:
+- [What was learned]
+
+---
+
+### Test 3: [Brief Test Description]
+**Date/Time**: [When]
+
+**Theory Being Tested**: [Theory name]
+
+**Test Procedure**:
+```bash
+[Commands]
+```
+
+**Expected Result**:
+[Description]
+
+**Actual Result**:
+```
+[Output]
+```
+
+**Analysis**:
+[Interpretation]
+
+**Conclusion**:
+- [What was learned]
+
+---
+
+## Solution
+
+### Root Cause
+[Detailed explanation of what was actually causing the error]
+
+### Fix Applied
+```bash
+[Exact commands or code changes made to resolve the issue]
+```
+
+### Why This Works
+[Explanation of why this solution resolves the root cause]
+
+### Verification
+**Verification Command**:
+```bash
+[Command to verify the fix]
+```
+
+**Verification Result**:
+```
+[Output showing the error is resolved]
+```
+
+**Additional Testing**:
+- [Test 1]: [Result]
+- [Test 2]: [Result]
+
+---
+
+## Lessons Learned
+
+### What Went Well
+- [Approach or technique that was effective]
+- [Tool or resource that was helpful]
+
+### What Could Be Improved
+- [Mistake or inefficiency to avoid in future]
+- [Better approach that could have been taken]
+
+### Key Insights
+- [Important insight 1]
+- [Important insight 2]
+- [Important insight 3]
+
+### Applicable to Future Cases
+- [General pattern or principle learned]
+- [Red flags to watch for in similar errors]
+- [Quick checks to try first next time]
+
+---
+
+## References
+
+### Documentation
+- [Link 1]: [Brief description]
+- [Link 2]: [Brief description]
+
+### Related Issues
+- [Link to similar GitHub issue, Stack Overflow question, etc.]
+
+### Tools Used
+- [Tool 1]: [What it was used for]
+- [Tool 2]: [What it was used for]
+
+---
+
+## Investigation Timeline
+
+**[HH:MM]** - Investigation started
+- Initial error encountered: [brief description]
+
+**[HH:MM]** - Extracted error template
+- Template: `[template]`
+
+**[HH:MM]** - Gathered environment information
+- [Key findings]
+
+**[HH:MM]** - Completed initial research
+- [Number] relevant sources found
+
+**[HH:MM]** - Formulated theories
+- [Number] theories developed
+
+**[HH:MM]** - Began testing
+- Started with Theory [N] (highest likelihood)
+
+**[HH:MM]** - Test 1 completed
+- [Result and conclusion]
+
+**[HH:MM]** - Test 2 completed
+- [Result and conclusion]
+
+**[HH:MM]** - Root cause identified
+- [Brief description]
+
+**[HH:MM]** - Fix applied
+- [Brief description]
+
+**[HH:MM]** - Fix verified
+- Error resolved successfully
+
+**[HH:MM]** - Investigation completed
+- Total time: [duration]
+
+---
+
+## Notes
+
+### Open Questions
+- [Question 1 that remains unanswered]
+- [Question 2 that needs clarification]
+
+### Future Investigation
+- [Area to explore if this error recurs]
+- [Related issue to investigate separately]
+
+### Blocked By
+- [If investigation is blocked, what's blocking it]
+- [What needs to happen to unblock]
+
+---
+
+## Metadata
+
+**Status**: [Active/Resolved/Blocked]
+**Priority**: [High/Medium/Low]
+**Tags**: [error-type, language, component, etc.]
+**Related Files**:
+- `[file1.py]`
+- `[file2.js]`
+**Related Errors**:
+- [Link to other debug notes if related]