Evidence-based debugging workflow for errors and bugs
Investigates errors using documented evidence from multiple authoritative sources before proposing fixes.
/plugin marketplace add flexion/claude-domestique/plugin install mantra@claude-domestiqueerror message or bug descriptionPerform evidence-based debugging using documented examples rather than guessing.
IMPORTANT: This skill implements the TROUBLESHOOTING & DEBUGGING rule from behavior.md
When the user reports an error, bug, or unexpected behavior, you MUST find documented evidence before proposing fixes. No guessing.
Gather Context
Research First Use these sources in order:
Cross-Reference Requirement
Pattern Matching Only after finding documented evidence:
Propose Solution
## Troubleshooting: [error summary]
### Context Gathered
- Error: [full message]
- Environment: [versions, platform]
- Action: [what user was doing]
### Research Findings
**Source 1**: [link or reference]
- Cause: [identified cause]
- Solution: [what worked]
**Source 2**: [link or reference]
- Cause: [identified cause]
- Solution: [what worked]
**Source 3**: [link or reference]
- Cause: [identified cause]
- Solution: [what worked]
### Analysis
[Common patterns across sources, applicability to user's case]
### Recommended Fix
[Solution with steps]
### Verification
[How to confirm the fix worked]
User: /mantra:troubleshoot TypeError: Cannot read properties of undefined (reading 'map')
Claude: ## Troubleshooting: TypeError on .map()
### Context Gathered
Let me get more details:
- Where does this error occur? (file:line)
- What data are you mapping over?
- Did this work before? What changed recently?
[After user provides context]
### Research Findings
**Source 1**: React GitHub Issue #14920
- Cause: API response returning undefined before data loads
- Solution: Add loading state or optional chaining
**Source 2**: Stack Overflow - verified answer with 200+ votes
- Cause: Component renders before async data arrives
- Solution: Initialize state with empty array, not undefined
**Source 3**: React Docs - Conditional Rendering
- Cause: Race condition between render and data fetch
- Solution: Guard clause or early return when data unavailable
### Analysis
All three sources point to the same root cause: trying to call .map() on data that hasn't loaded yet. Your fetch likely returns undefined on error or hasn't completed.
### Recommended Fix
```javascript
// Before
{items.map(item => ...)}
// After - Option 1: Optional chaining
{items?.map(item => ...) ?? null}
// After - Option 2: Guard clause
{items && items.length > 0 && items.map(item => ...)}
// After - Option 3: Loading state (preferred)
if (!items) return <Loading />;
return items.map(item => ...);
## When to Use
Invoke this skill when:
- User reports an error message
- Something "stopped working"
- Unexpected behavior occurs
- User asks "why is this happening?"
## When Stuck
If you can't find 3 documented examples:
- Ask user for more context (exact error, reproduction steps)
- Search with different keywords
- Check if this is a new/unreported issue
- Do NOT guess - say "I couldn't find documented cases for this specific issue"