documenting-debugging-workflows
Create symptom-based debugging documentation that matches how developers actually search for solutions
When & Why to Use This Skill
This Claude skill empowers developers and technical writers to create highly effective, symptom-based debugging documentation. By shifting the focus from root causes to observable behaviors, it ensures that troubleshooting guides and 'FIX' sections align with how developers naturally search for solutions, significantly reducing the time-to-resolution for complex technical issues.
Use Cases
- Building a comprehensive 'Troubleshooting' section for open-source projects or internal documentation that categorizes issues by what the user actually sees (e.g., 'Slow Startup' vs 'Memory Leak').
- Converting scattered bug reports, Slack discussions, and support tickets into a structured, searchable knowledge base with standardized investigation steps.
- Creating quick-diagnosis tables for DevOps and SRE teams to accelerate incident response by mapping symptoms to likely causes and runnable commands.
- Standardizing how engineering teams document recurring bugs to ensure that fixes include prevention strategies and clear escalation paths.
| name | Documenting Debugging Workflows |
|---|---|
| description | Create symptom-based debugging documentation that matches how developers actually search for solutions |
| when_to_use | when creating debugging guides, documenting common bugs, building troubleshooting documentation, or organizing FIX/ sections |
| version | 1.0.0 |
Documenting Debugging Workflows
Overview
Create debugging documentation organized by observable symptoms, not root causes. Developers search by what they see, not by what's wrong.
Announce at start: "I'm using the documenting-debugging-workflows skill to create symptom-based debugging docs."
When to Use
- Creating debugging documentation for a project
- Documenting common bugs and their fixes
- Building troubleshooting guides
- Organizing FIX/ section content
- Recurring issues need documentation
Core Principle
Wrong: Organize by root cause (memory-leaks/, type-errors/) Right: Organize by observable symptom (visual-bugs/, slow-startup/)
Developers don't know the root cause when they start debugging - they know what they observe.
The Process
Step 1: Collect Symptoms
Gather observable symptoms from:
- Bug reports and issues
- Support tickets
- Slack/team chat questions
- Your own debugging sessions
- Code review comments
For each symptom, note:
- What exactly does the developer see?
- How do they describe it?
- What words do they use to search?
Step 2: Create Symptom Categories
Group symptoms by observable category:
FIX/
├── symptoms/
│ ├── visual-bugs/ # "Rendering looks wrong"
│ ├── performance/ # "It's slow"
│ ├── test-failures/ # "Tests fail"
│ ├── build-errors/ # "Won't compile"
│ └── data-issues/ # "Data is wrong"
├── investigation/
│ └── systematic-debugging.md
└── solutions/
└── common-fixes.md
Choose categories based on YOUR project's common issues.
Step 3: Build Quick Diagnosis Table
Create the entry point with a scannable table:
# [Category] Debugging Guide
## Quick Diagnosis
| Symptom | Likely Cause | Investigation | Priority |
|---------|--------------|---------------|----------|
| [What you see] | [Root cause] | [Link] | ⚠️ High |
| [What you see] | [Root cause] | [Link] | ☠️ Critical |
Priority icons:
- ☠️ Critical (production impact)
- ⚠️ High (blocking work)
- 🎯 Medium (should fix soon)
- ✅ Low (minor annoyance)
Step 4: Document Each Symptom
For each symptom, create structured documentation:
- What You See - Exact observable behavior
- Likely Causes - Ordered by probability
- Investigation Steps - With commands to run
- Solutions - Fixes for each cause
- Prevention - How to avoid in future
Use template: ${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md
Step 5: Create Investigation Strategies
Document systematic approaches in investigation/:
- How to reproduce consistently
- How to isolate the problem
- Gathering evidence (logs, metrics)
- Forming and testing hypotheses
- Binary search for breaking changes
Step 6: Build Solutions Catalog
Document known fixes in solutions/:
- Common error codes and fixes
- Proven workarounds
- Configuration fixes
- Code patterns that prevent issues
Step 7: Add Escalation Guidance
Document when to escalate:
- Time thresholds (stuck > X hours)
- Impact thresholds (production, data, security)
- Who to contact
- What information to gather first
Step 8: Verify and Maintain
- Test documentation with someone unfamiliar
- Update when new symptoms discovered
- Archive outdated fixes (don't delete - mark as historical)
- Track which docs get used most
Checklist
- Symptoms collected from real sources
- Categories match project's common issues
- Quick diagnosis table created
- Each symptom has structured documentation
- Investigation strategies documented
- Solutions catalog started
- Escalation guidance clear
- Tested with fresh eyes
Anti-Patterns
Don't:
- Organize by root cause (developers don't know it yet)
- Skip the quick diagnosis table
- Write investigation steps without commands
- Forget escalation guidance
- Let docs become stale
Do:
- Use exact symptom descriptions
- Include runnable commands
- Link to related docs liberally
- Update when fixes are found
- Track which docs help most
Example: Visual Bug Entry
## Rendering Artifacts on Screen
### What You See
Flickering textures, z-fighting, or objects appearing through walls.
### Likely Causes
1. **Floating point precision** (most common)
- Objects far from origin
- Verify: Check object world coordinates
2. **Z-buffer precision**
- Near/far plane ratio too large
- Verify: Check camera settings
### Investigation Steps
1. [ ] Log object world coordinates
```rust
info!("Position: {:?}", transform.translation);
If > 10000 units from origin → floating point issue
- Check camera near/far planes
If ratio > 10000 → z-buffer issueinfo!("Near: {}, Far: {}", camera.near, camera.far);
Solutions
If floating point: Implement floating origin If z-buffer: Adjust camera planes
Prevention
- Use floating origin for large worlds
- Keep near plane as far as acceptable
## Related Skills
- **Organizing documentation:** `${CLAUDE_PLUGIN_ROOT}skills/organizing-documentation/SKILL.md`
- **Creating research packages:** `${CLAUDE_PLUGIN_ROOT}skills/creating-research-packages/SKILL.md`
- **Creating quality gates:** `${CLAUDE_PLUGIN_ROOT}skills/creating-quality-gates/SKILL.md`
## References
- Standards: `${CLAUDE_PLUGIN_ROOT}standards/documentation-structure.md`
- Template: `${CLAUDE_PLUGIN_ROOT}templates/symptom-debugging-template.md`