urmzd/dotfiles / dot_agents/skills/triage-dotfiles-env
triage-dotfiles-env
UnverifiedPlaybook of known failure modes in this dotfiles stack: pipx "bad interpreter" after Python rebuilds, gpg commit-signing failures, direnv/nix shellHook running bash instead of zsh, Powerlevel10k instant-prompt warnings, and Neovim plugin errors from removed Lua APIs. Use when a shell startup error, git signing failure, broken CLI shim, or nvim stack trace appears on this machine. Do NOT use for generic runtime debugging in projects (use diagnose-runtime), chezmoi naming and templating conventions (use dotfiles), or authoring pinned installers (use setup-devenv-with-chezmoi).
Triage Dotfiles Environment
Look the symptom up here before debugging from scratch. Every fix ends with its verification step; a fix without verification is not done.
Known failure modes
pipx shims: "bad interpreter: no such file or directory"
Seen repeatedly in .zshrc completions (register-python-argcomplete: bad interpreter).
- Cause: a Homebrew or uv Python upgrade rebuilt the interpreter path; every pipx venv shebang now points at a deleted Python.
- Fix:
pipx reinstall-all. If pipx itself is broken:brew reinstall pipx && pipx reinstall-all. - Verify: open a fresh
zsh -land confirm zero startup errors, then run the failing shim directly.
gpg: "cannot run gpg: No such file or directory" on commit
- Cause: git config points at a gpg binary that moved (brew relink,
new machine), or
GPG_TTYis unset in a non-login context. - Fix:
git config --global gpg.program "$(command -v gpg)", ensure the zshrc exportsGPG_TTY=$(tty), and confirmuser.signingkeymatchesgpg --list-secret-keys --keyid-format long. - Verify:
git commit --allow-empty -m "test: signing" && git log --show-signature -1, then drop the test commit.
direnv + nix: shellHook runs bash, not zsh
Symptoms: aliases and functions missing inside a nix shell, prompts wrong, zsh-only syntax errors from hooks.
- Cause: nix shellHook always executes in bash. zsh config never runs.
- Fix: keep shellHook to environment exports only; put interactive setup
in zsh init guarded by
IN_NIX_SHELL. Never source zsh files from shellHook. - Verify:
direnv exec . zsh -ic 'echo $SHELL; alias | head'.
Powerlevel10k instant-prompt warnings
- Cause: something in
.zshrcprints output before the instant-prompt block (installer scripts, completion generators, version managers). - Fix: move the offending line below the instant-prompt block or silence its output; keep the instant-prompt block first.
- Verify: fresh
zsh -lshows no warning banner.
Neovim: plugin errors from removed Lua APIs
Example: E5108 ... attempt to call field 'buf_get_clients' (a nil value)
(API removed; modern equivalent vim.lsp.get_clients).
- Cause: plugin pinned by lazy.nvim lockfile predates a Neovim HEAD API removal, or an abandoned plugin needs replacement.
- Fix:
:Lazy updatethe plugin first; if abandoned, patch the call or swap the plugin. Check~/.local/state/nvim/logfor the full trace. - Verify:
nvim --headless "+lua print('ok')" +qexits clean, then open a file that previously triggered the error. A pasted-twice error means the first fix was never verified; always run this step.
Completions stale after adding or removing CLIs
- Cause: generated completions in the chezmoi-managed dir lag the installed tool set.
- Fix: re-run the completion generation script via
chezmoi apply(it is anrun_onchangescript keyed to the Brewfile and zshrc). - Verify:
zsh -ic 'compdef | grep <tool>'.
Method for anything not listed
- Reproduce in a fresh shell (
zsh -lorzsh -ic '<cmd>'), never only in the current polluted session. - Bisect the init chain:
zsh -df(clean), then add zshrc, then direnv, then nix. The first layer that reproduces owns the bug. - Fix in the chezmoi source (
chezmoi edit), apply, and re-verify from a fresh shell. - Add the new failure mode to this skill so it is a lookup next time.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |