LLM Wiki Doctor

LLM Wiki Doctor

Purpose

Run and interpret LLM Wiki Doctor for a project-local .llm-wiki.

Default to read-only diagnosis. Use deterministic validate for hard validator findings and report for human-facing Chinese maturity reports. Do not repair files unless the user explicitly asks for repair or completion.

Initialization Gate

Run after resolving the project root and before resolving or running a Doctor script.

• wiki_required: true
• on_missing_wiki: route project-init
• direct_invocation_missing_wiki: dispatch-project-init
• When directly invoked and no parent router is active, treat the bootstrap handoff as an internal routing message, not a terminal user-facing response.
• Unless an explicit no-write constraint or root-confidence check requires confirmation, continue through project-init in the same turn, consume its return handoff, and resume only at a supported next gate.
• pending_primary_stage: llm-wiki-doctor
• Preserve the user's original diagnosis request as pending_intent.
• If <project_root>/.llm-wiki/ is absent, stop and return a Context Handoff to project-init with bootstrap_mode: automatic-minimal.
• Do not run the Doctor, create a partial .llm-wiki/, or report a Wiki health result when the Wiki does not exist.
• Default read-only diagnosis does not mean the user forbids bootstrap writes. Ordinary health-check requests use automatic minimal bootstrap, then resume Doctor.
• Only an explicit no-write constraint pauses for confirmation before initialization.

On the missing-wiki branch, emit this minimal handoff:

bootstrap_handoff:
  project_root: <resolved project root>
  pending_intent: <preserved diagnosis request>
  pending_primary_stage: llm-wiki-doctor
  requested_stage_or_bridge: project-init
  bootstrap_mode: automatic-minimal
  current_gate: Initialization Gate

Required First Check

1. Resolve the project root.
2. Run the Initialization Gate.
3. Resolve the doctor script from .llm-wiki/tools/llm_wiki_doctor.py, then the bundled ../scripts/llm_wiki_doctor.py.
4. For CI, pre-commit, project-finish, or blocking failures, run validate.
5. Otherwise run report and explain the Chinese report.

Commands

Human diagnosis:

python <doctor> report --root . --phase advisory --format text

Machine checks:

python <doctor> validate --root . --changed --phase normal --format text --fail-on error
python <doctor> validate --root . --base origin/main --phase normal --format json --fail-on error
python <doctor> validate --root . --phase finish --format text --fail-on error

Structured maturity signals:

python <doctor> score --root . --phase advisory --format json

Interpretation Rules

• Treat validate findings as deterministic script output.
• Treat score as directional maturity guidance, not a KPI.
• Report not-applicable dimensions instead of penalizing simple projects.
• Use script signals as evidence for semantic judgments. Do not invent project facts from the score.
• Keep Project Graph and module-context findings visible: missing-graph-evidence, invalid-edge-id, dangling-cross-ref, duplicate-edge-fingerprint, leaked-local-path, missing-module-context, incomplete-module-context, thin-module-context, missing-module-evidence, and contradictory-module-context.
• Interpret module signals in two layers: wiki_module_context_count means the scoped directory exists; ready_module_context_count means required files are present, non-placeholder, and source-backed.
• Keep knowledge anti-corruption findings visible: missing-origin, missing-source-refs, missing-verified-commit, freshness-expired, unresolved-dirty-capture, unreachable-verified-commit, stale-source-anchor, coarse-stale-source-anchor, unverifiable-anchor, and suspicious-confidence.
• Keep edge detail findings visible: missing-edge-detail-id, invalid-edge-detail-id, and duplicated-edge-detail-fact.
• Treat report as consulting output; it should explain the health score and exit successfully even when it includes validate findings. Treat validate --fail-on error as the blocking command for pre-commit, CI, and project-finish.
• Use --phase advisory for human diagnosis, --phase normal for routine local/CI checks, and --phase finish for project-finish. In finish phase, unresolved dirty captures are blocking because handoff should not archive unclean captured facts as verified knowledge.

Repair Boundary

Default to read-only. When the user explicitly asks to repair, route structural repairs to project-maintain unless the repair is limited to installing or running the doctor. Never auto-fill semantic content such as module responsibilities, API contracts, requirement scope, bug conclusions, confirmed Project Graph edges, or verification status.