---
description: "Save a troubleshooting entry for a bug fix or incident resolution"
allowed-tools: Read,Write,Edit,Glob,Grep,Bash
---

Save a troubleshooting doc capturing a bug fix, incident, or resolved issue. Checks for an existing troubleshooting file in the domain to append to.

## Defaults

- **type:** `troubleshooting`
- **tags:** always include `troubleshooting`
- **save path:** `/mnt/NV2/Development/claude-home/{domain}/`

## Before Writing

1. **Check for existing file** — look for `{domain}/troubleshooting.md` in the KB directory. If one exists, **append** a new section rather than creating a separate file.
2. **If creating a new standalone file** — use a descriptive hyphenated name (e.g., `scout-token-wallet-fix.md`)
3. **Ask the user** for domain if not obvious from context

## Document Structure — Standalone File

```markdown
---
title: "Fix: {Short description of the problem}"
description: "One-line summary of what broke and why."
type: troubleshooting
domain: {domain}
tags: [troubleshooting, ...]
---

# Fix: {Short description}

**Date:** YYYY-MM-DD
**PR:** #{number} (if applicable)
**Severity:** {Low | Medium | High | Critical} — {brief impact}

## Problem

What was happening? What was the user-visible symptom?

## Root Cause

Why was it happening? Be specific about the code path or misconfiguration.

## Fix

What was changed? Include the approach, not a full diff.

## Lessons

- What should be done differently in the future?
- Any new tests, guards, or patterns established?
```

## Document Structure — Appending to Existing File

When appending to an existing `troubleshooting.md`, add a new `##` section with this format:

```markdown
## {Short description} ({YYYY-MM-DD})

**Severity:** {level} — {impact}

**Problem:** {symptom}

**Root Cause:** {why}

**Fix:** {what changed}

**Lesson:** {takeaway}
```

## Rules

- Always check for an existing troubleshooting file first
- Include severity to help prioritize similar issues in the future
- Focus on the "why" in Root Cause — not just "what was wrong" but why it happened
- Lessons should be actionable — patterns to follow or avoid, not just "be more careful"