菜单
Use on "command not found", the shell won't enter, or eval errors. A symptom→cause→fix decision tree for devenv repos.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | devenv-troubleshoot |
| description | Use on "command not found", the shell won't enter, or eval errors. A symptom→cause→fix decision tree for devenv repos. |
| auto_trigger | {"keywords":["command not found","shell won't enter","eval error","devenv broken","won't build","infinite recursion","attribute missing","devenv fails"]} |
| Symptom | Likely cause | Fix |
|---|---|---|
command not found for a project CLI | running outside the shell, or deps not synced | devenv shell -- <cmd>; sync the venv → devenv-python-venv |
ModuleNotFoundError on import | venv exists but deps unsynced | uv sync / repoman-sync → devenv-python-venv |
| Edited a module, no effect | stale lock / eval cache | rm -f devenv.lock && rm -rf .devenv → devenv-module-edits |
| Import of a module fails | missing flake: false or transitive input | devenv-inputs |
| Python version pin ignored | no nixpkgs-python input | devenv-inputs |
| Shell won't enter / eval error | bad .nix syntax or stale eval cache | re-read the error; devenv shell --refresh-eval-cache; for the full reset rm -rf .devenv |
| Server ties up the shell | used scripts for a daemon | use processes + devenv up → devenv-processes |
Background on how PATH is assembled (venv vs nix vs scripts): command-not-found-in-shell.md.
For when in the lifecycle to stop and fix vs. proceed, see the repoman skill.
Use when writing a scripts/tasks/processes entry or a manager module. Covers which surface to use, guarding enterShell echoes, and the 0/1/2/3 exit contract.
Use when editing devenv.yaml or adding an input/import. Covers flake:false for modules, nixpkgs-python for version pins, and transitive inputs.
Use when you edited a modules/ file, devenv.nix, or env.* and nothing changed. Resolves the lock + eval-cache staleness loop.
Use when starting a server or any long-running / heavy task. Use processes + devenv up; don't block the shell; poll logs instead of piping out of view.
Use on ModuleNotFoundError or import failures inside the devenv shell, or after a fresh venv. The venv exists but deps may not be installed.
Use when about to run pytest, python, uv, ruff, or any build/tooling command in this repo. Enforces running through the devenv shell.
