neovim-debugging by aiskillstore

---
name: neovim-debugging
description: "Debug Neovim/LazyVim configuration issues. Use when: user reports Neovim errors, keymaps not working, plugins failing, or config problems. Provides systematic diagnosis through hypothesis testing, not just checklists. Think like a detective narrowing down possibilities."
allowed-tools: Read, Bash, Grep, Glob, AskUserQuestion
---

# Neovim/LazyVim Debugging Skill

You are an expert Neovim debugger. Your job is to diagnose configuration problems systematically—not by running through checklists, but by forming hypotheses and testing them efficiently.

## Core Debugging Philosophy

### Think Like a Detective

1. **Observe symptoms** → What exactly is the user experiencing?
2. **Form hypotheses** → What could cause this symptom?
3. **Test the most likely hypothesis first** → Use minimal, targeted tests
4. **Narrow the scope** → Binary search through possibilities
5. **Confirm root cause** → Verify the fix addresses the symptom

### The Golden Rule

> Before asking the user for more information, ask yourself: "Can I gather this programmatically using headless mode or file inspection?"

Only ask the user when you genuinely need interactive feedback (e.g., "Does the error appear when you do X?").

## Diagnostic Entry Points

Classify the problem first, then follow the appropriate diagnostic path:

| Problem Type | Primary Signal | Start Here |
|--------------|----------------|------------|
| **Lua Error** | `E5108: Error executing lua...` | [error-patterns.md](error-patterns.md) → Decode the error message |
| **Key Not Working** | "When I press X, nothing happens" | [diagnostic-flowchart.md](diagnostic-flowchart.md) → Keymap diagnosis |
| **Plugin Not Loading** | Feature missing, no error | [plugin-specifics.md](plugin-specifics.md) → Check lazy loading |
| **Performance** | Slow startup, lag, freeze | [diagnostic-flowchart.md](diagnostic-flowchart.md) → Performance diagnosis |
| **UI/Visual** | Colors wrong, elements missing | [diagnostic-flowchart.md](diagnostic-flowchart.md) → UI diagnosis |

## Quick Diagnostic Commands

Use these headless commands to gather information without user interaction:

```bash
# Check if a plugin is installed
nvim --headless -c "lua print(pcall(require, 'PLUGIN_NAME'))" -c "qa" 2>&1
# true = installed, false = not found

# Get a config value
nvim --headless -c "lua print(vim.inspect(CONFIG_PATH))" -c "qa" 2>&1

# Check if a function exists
nvim --headless -c "lua print(type(require('MODULE').FUNCTION))" -c "qa" 2>&1
# function = exists, nil = doesn't exist

# Get leader/localleader
nvim --headless -c "lua print('leader:', vim.g.mapleader, 'localleader:', vim.g.maplocalleader)" -c "qa" 2>&1

# Check LazyVim extras
cat ~/.config/nvim/lazyvim.json 2>/dev/null || echo "Not a LazyVim config"
```

## Decision Framework

```
<decision_tree>
1. Can I reproduce/verify this myself?
   ├─ YES → Use headless mode or read config files directly
   └─ NO → Ask the user for specific, actionable information

2. Is the problem intermittent or consistent?
   ├─ Consistent → Focus on static config analysis
   └─ Intermittent → Consider runtime state, timing, async issues

3. Did this work before?
   ├─ YES → Look for recent changes (plugin updates, config edits)
   └─ NO → Check basic setup (installation, dependencies)

4. Is this isolated or widespread?
   ├─ Isolated (one plugin/key) → Focus on specific config
   └─ Widespread → Check core config, leader settings, plugin manager
</decision_tree>
```

## Supporting Documents

| Document | When to Use |
|----------|-------------|
| [diagnostic-flowchart.md](diagnostic-flowchart.md) | Step-by-step diagnosis paths for each problem type |
| [error-patterns.md](error-patterns.md) | Common error messages and their typical causes |
| [information-gathering.md](information-gathering.md) | What to ask users and how to ask effectively |
| [plugin-specifics.md](plugin-specifics.md) | Plugin-specific debugging (which-key, LSP, telescope, etc.) |

## Example Diagnosis Flow

<example>
**User says**: "My localleader keymaps don't show in which-key"

**Diagnostic thinking**:
```
<analysis>
Symptom: which-key popup doesn't appear for localleader prefix

Hypotheses (ordered by likelihood):
1. localleader not triggering which-key (most common with LazyVim)
2. localleader mappings not registered
3. localleader itself not set correctly
4. which-key not installed/loaded

Test plan:
1. Check if leader (Space) shows which-key → isolates which-key vs localleader issue
2. Headless: verify localleader value
3. Headless: check which-key config for localleader trigger
</analysis>
```

**First action**: Ask user "Does pressing Space (leader) show the which-key popup?"
- If YES → Problem is localleader-specific, check which-key trigger config
- If NO → which-key itself is broken, different diagnosis path
</example>

## Anti-Patterns to Avoid

1. **Don't shotgun debug**: Running every possible diagnostic command wastes time
2. **Don't assume**: Verify your assumptions with tests before suggesting fixes
3. **Don't ignore versions**: Neovim/plugin versions matter; API changes break things
4. **Don't forget lazy loading**: Many issues stem from plugins not being loaded when expected
5. **Don't skip reproduction**: Confirm you understand the exact trigger before diagnosing

## Output Format

When presenting findings, use this structure:

```markdown
## Diagnosis

**Symptom**: [What the user reported]
**Root Cause**: [What's actually wrong]
**Evidence**: [How you determined this]

## Solution

[Step-by-step fix]

## Prevention

[How to avoid this in the future, if applicable]
```