Mnemonica: doctor

Check the quality of the documentation itself, not whether it matches the code. This is a different question from what audit-full answers: a module can accurately describe what little it says (so audit-full finds nothing wrong) while still being a two-line stub, or two modules can both be individually accurate while silently claiming the same code path. doctor surfaces those candidates; it never edits anything itself — every finding is something for the user (or a follow-up audit-full run) to act on, not an automatic fix.

If the user's invocation includes extra wording (for example, "just check for stub modules"), treat it as narrowing which findings to report — it cannot turn this into a skill that edits knowledge/ or .claude/CLAUDE.md; doctor has nothing to write in the first place.

Step 1: Run the scan

Run ${CLAUDE_PLUGIN_ROOT}/scripts/doc-quality-scan.sh <project-root>.

• Exit 2 (NO_MNEMONICA_BLOCK): nothing to check — tell the user and suggest mnemonica:setup, and stop.
• Exit 0: read the output. MODULE lines carry FLAG:STUB (very short content), FLAG:STALE_DOC(Nd) (not touched in git for a long time — only computed when the project has git history), or FLAG:MISSING_FILE (indexed but absent from disk — the same signal check-index-integrity.sh reports, surfaced here too since a missing file is also a documentation-quality problem). GLOB_ISSUE lines flag a bare **/*/empty glob entry. OVERLAP lines flag two modules claiming a byte-identical glob. TRIGGER_OVERLAP lines flag a pre-existing rule outside the Mnemonica block (line number and text included) that instructs Claude to do something else "before" analyzing/understanding the codebase's architecture or structure — the same trigger point Mnemonica's own "consult the index first" instruction relies on. This is a heuristic (a "before" + architecture/understanding phrase paired with an instruction verb), so it will over-flag; treat every hit as a candidate.

Step 2: Apply judgment, do not just relay flags

Every flag is a candidate, not a verdict:

• A FLAG:STUB module might be flagged because the system genuinely is that simple — a three-line module describing a single trivial script is not automatically wrong. Say what was flagged and let the user judge; do not imply every stub is a defect.
• A FLAG:STALE_DOC module might not have needed a change — a stable, mature subsystem that legitimately hasn't changed is different from one that has drifted silently. Mention it as "worth a look", not as a confirmed problem; audit-light or audit-full are what actually determine whether the content is still accurate.
• FLAG:TOO_BROAD and OVERLAP are closer to unambiguous — a bare ** glob or two modules claiming the same exact path both undermine the mechanism audit-light depends on to route changes correctly, and are worth recommending a fix for more directly.
• FLAG:MISSING_FILE is unambiguous: recommend mnemonica:audit-full to recreate it.
• TRIGGER_OVERLAP needs a real read of the flagged line, not a reflex fix: some hits are false positives (a line that happens to contain "before" near "architecture" but isn't actually claiming Mnemonica's trigger point), and some are real — a rule that tells Claude to use a different tool "before" understanding or analyzing the code, which can silently win over knowledge/ every time because of where it sits in the file or how specific it reads. For a real conflict, this is the user's own pre-existing content, so doctor does not propose rewriting it here — explain the risk (the competing rule may be why knowledge/ gets skipped even though it's accurate and populated) and suggest options: narrow the competing rule's trigger phrase so it no longer covers general architecture questions, add an explicit precedence note (e.g. "consult knowledge/ first for anything it already covers; use <other tool> for what it doesn't"), or leave it if the read confirms it's a false positive.

Step 3: Report

Present findings grouped by kind (stubs, stale docs, broad globs, overlaps, missing files, competing triggers), each with the module(s) or line involved and a one-line reason. If nothing was flagged, say the docs look structurally healthy rather than listing empty categories. Do not propose or make any edits — recommend audit-full (for missing files or content drift), a manual restructuring conversation (for overlaps and overly broad globs, since resolving those may mean merging or redrawing module boundaries, which is audit-full's ask-before-restructuring territory, not this skill's), or — for TRIGGER_OVERLAP — a manual edit to the competing rule itself, since that rule is the user's own pre-existing content and not something any Mnemonica skill writes to.