night-market-debugging-playbook

# Night Market Debugging Playbook Match the symptom to a row, run the one discriminating command, apply the known fix. Every row below is a failure this repo has already paid for, with the commit hash that settled it. Do not re-derive a diagnosis that archaeology already produced. ## Vocabulary Terms used throughout, defined once: - **Hook**: a script Claude Code runs on events (PreToolUse, PostToolUse, Stop, SessionStart). Registered in a plugin's `hooks/hooks.json` with a `command` and a `timeout`. - **Hook budget**: that registered `timeout` in seconds. The harness kills the hook when it expires, before any output is honored. - **Host interpreter**: hooks run as `python3 ...` under the machine's system Python (floor: 3.9), NOT the repo's uv-managed 3.12 venv. Third-party packages a plugin declares are not guaranteed present. - **skrills**: optional Rust binary for skill validation and analysis. Every Makefile target that uses it has a Python fallback. - **Import chain**: everything a `import x` transitively pulls in, including the plugin's `__init__.py`. ## Symptom index | # | Symptom | Likely cause | Story | |---|---------|--------------|-------| | 1 | PreToolUse hook error / ModuleNotFoundError on every `git commit` | Unguarded third-party import in a plugin `__init__.py` reachable from a hook | 45dd77ef, 9bfc0a7a | | 2 | `python39-compat` is the only failing CI check | A 3.10+/3.11+ construct (`datetime.UTC`, bare `X \| Y` union) entered a hook impor...