| name | nvim |
| description | Use when troubleshooting Neovim plugin errors, updating plugins after breaking changes, or diagnosing colorscheme/startup issues in this vim.pack-based config. |
| argument-hint | [debug | update | fix <plugin>] |
| model | sonnet |
| context | default |
| allowed-tools | ["Read","Glob","Grep","Bash(nvim --version:*)","Bash(nvim --headless:*)","Bash(tmux new-session -d -s nvim-debug:*)","Bash(tmux kill-session -t nvim-debug:*)","Bash(tmux capture-pane -t nvim-debug:*)","Bash(ls:*)","Bash(cat /tmp/nvim-debug*:*)","Bash(git -C ~/.local/share/nvim/site/pack/core/opt:*)","Bash(chezmoi diff:*)","Bash(chezmoi status:*)","Bash(sleep:*)"] |
Neovim Troubleshooting & Updates
This config is not LazyVim. Plugins are managed by vim.pack (Neovim 0.12+ built-in). No lazy.nvim, no LazyVim distribution, no snacks. See docs/neovim.md for the full layout.
Arguments
$ARGUMENTS
Key Paths
| What | Source (edit here) | Installed (read-only) |
|---|
| Plugin specs | home/dot_config/nvim/plugin/00-packs.lua | ~/.config/nvim/plugin/00-packs.lua |
| Per-plugin config | home/dot_config/nvim/plugin/<name>.lua | ~/.config/nvim/plugin/<name>.lua |
| Core modules | home/dot_config/nvim/lua/{options,ui,window,keymaps,autocmds}.lua | ~/.config/nvim/lua/... |
| Lockfile (committed) | home/dot_config/nvim/nvim-pack-lock.json | ~/.config/nvim/nvim-pack-lock.json |
| Installed plugins | — | ~/.local/share/nvim/site/pack/core/opt/<plugin>/ |
Always edit source (home/dot_config/nvim/), never destination. Deploy with chezmoi apply.
Mode: debug (default)
Use tmux, not headless — --headless skips UI plugins (lualine, blink.cmp, oil) so it hides real errors. The debug script also relies on vim.pack having finished its install/update pass.
- Copy debug script:
cp .claude/skills/nvim/nvim-debug.lua /tmp/nvim-debug.lua
- Launch:
tmux new-session -d -s nvim-debug -x 200 -y 50 "nvim -S /tmp/nvim-debug.lua"
- Wait + read:
sleep 8 && cat /tmp/nvim-debug-output.txt
- Check
[ERROR] lines — these come from :messages (where vim.pack, LSP, and plugins route errors)
Mode: fix <plugin>
- Compare lockfile vs. installed rev:
nvim-pack-lock.json records pinned rev. Check git -C ~/.local/share/nvim/site/pack/core/opt/<plugin> rev-parse HEAD — drift means an out-of-band update broke things.
- Find the breaking commit:
git -C ~/.local/share/nvim/site/pack/core/opt/<plugin> log --oneline --grep="BREAKING\|refactor!\|breaking" --all
- Edit source in
home/dot_config/nvim/plugin/00-packs.lua (pin a version) or the sibling plugin/<plugin>.lua (adjust setup call). Run chezmoi diff then chezmoi apply.
- Clear compiled cache if theme-related:
rm -rf ~/.cache/catppuccin. Catppuccin is the only theme that compiles.
- Re-run debug mode to verify.
- Sync lockfile back to source after a successful run:
cp ~/.config/nvim/nvim-pack-lock.json home/dot_config/nvim/nvim-pack-lock.json. vim.pack writes the destination copy; the source copy is what's committed.
Mode: update
- Run
:lua vim.pack.update() in a real Neovim session. It opens a confirm buffer; review the diff and :write to apply.
- Run debug mode to catch breakage.
- Sync lockfile back to source (see step 6 above).
Anti-patterns
- Never treat this like a LazyVim config. There is no
:Lazy, no lua/plugins/, no lazy-lock.json, no snacks.notifier. Don't look for upstream LazyVim fixes — there is no upstream distribution.
- Never use inline
-c "lua ..." — shell escaping mangles quotes. Write temp Lua files.
- Never edit
~/.config/nvim/ directly — chezmoi owns the destination.
- Never ignore lockfile drift — sync the installed lockfile back to source or breakage recurs on the next
chezmoi apply to a fresh machine.
Examples
/nvim → Run debug, report errors
/nvim fix catppuccin → Fix catppuccin after breaking update
/nvim update → Update all plugins, debug, sync lockfile
