Haruki1090 doctor
plumb-doctor
The script holds the judgment. This document holds only when to run it, and what to suspect when it fails. Copy the steps here and one copy goes stale (principle-encode-lessons-in-structure).
Why it is needed
plumb is a bundle of documents that assert facts about the environment: which command exists, which skill exists, which path exists.
Unlike code, those assertions say nothing when they break. A document happily survives the disappearance of what it points at, and sends the next reader somewhere that is not there.
Two of them turned up in a single session on 2026-08-29.
~/.<tool>-worktrees/ a carry-over note named it; the path did not exist
the pr-review skill six agents introduced themselves as "called from stage N of the
pr-review skill", but that skill had been moved aside and was not live
Neither shows up under grep or lint. "Something that should be there is not" is only knowable by going and checking that it is. So it became a tool (principle-build-the-lever).
When to run it
- At the end of a batch. As part of the termination condition.
- After you change the environment. A skill added, removed or moved aside; an extension installed; a CLI swapped.
- When you come back to plumb after a while. When you do not know what moved since last time.
- When you followed a pointer out of the
plumbindex and it was not there. Do not fix that one item; look at the whole first.
Reading a failure
| Where it failed | What to suspect |
|---|---|
| Inside (cross-cutting rules) | an edit to plumb itself. Run plumb-check directly and read what it says |
| Inside (script behavior) | selftest.sh's own premises may be broken. Run plumb-selftest directly and read what it says |
| Routing targets | PATH and the extension install. The premises of docs/role-map.md have collapsed |
| Bundled agents | one of agents/ was deleted or renamed. Cross-check the names skills/pr-review/SKILL.md calls against what is actually in agents/ |
| The agents on your side (your own copy) | the same cause, showing up on your own ~/.claude/agents/ side. Either put the skill back, or fix the agent's description |
| Paths | docs/path-map.md's claim is out of date. Measure first, then fix the table. Do not rewrite it from a guess |
| Loading | check the plugin list for the selected runtime in a new session; use the runtime adapter for command mapping |
Do not bury a failing item. Loosening the expectation to get doctor to pass is
killing the verifier (principle-prove-it-works).
If you cannot fix it, write "this is broken right now" into docs/ and leave it there.