neovim-debugging_skill

Overview

This skill diagnoses Neovim and LazyVim configuration problems by thinking like a detective. It narrows causes with hypothesis-driven tests and uses headless commands and file inspection to gather evidence before asking the user. The goal is to find a root cause and provide a minimal, verifiable fix.

How this skill works

I classify the reported symptom, form ranked hypotheses, then run targeted, minimal tests (often using nvim --headless or inspecting config files). Tests follow a binary-search approach: rule out large classes of causes first, then narrow to specific plugins, keymaps, or Lua errors. Final steps confirm the fix reproduces the resolved behavior.

When to use it

• Neovim shows Lua errors (E5108 or similar).
• Keymaps or leader/localleader mappings don’t trigger actions.
• Plugins appear missing, features not loaded, or lazy-loading seems broken.
• Startup performance issues, excessive latency, or freezes.
• Visual/UI problems: colors, missing elements, or statusline glitches.

Best practices

• Collect a precise symptom description and reproduce steps before deep debugging.
• Prefer headless inspection (nvim --headless) to gather deterministic evidence without user environment changes.
• Test hypotheses in order of likelihood and keep tests minimal and reversible.
• Binary-search config changes: disable halves of config/plugins to quickly isolate the culprit.
• Record evidence (error messages, headless outputs) and confirm the fix by reproducing the original symptom.

Example use cases

• Resolve E5108 Lua error originating from a plugin config by inspecting stack traces and the specific module.
• Fix leader/localleader which-key behavior by verifying leader values and whether which-key loaded for that prefix.
• Diagnose a plugin that doesn’t load due to lazy-loading misconfiguration by checking plugin load conditions in headless mode.
• Investigate slow startup by identifying heavy plugins or expensive config using selective disabling and timing.
• Repair missing UI elements (colorschemes, statusline) by checking plugin availability and runtimepath ordering.