avinycqmd-doctor

name	avinyc:qmd-doctor
description	Run qmd health check for this project. Triggers on "qmd doctor", "check qmd health", "qmd problems", "diagnose qmd".
user-invocable	true
allowed-tools	["Bash","Read","Glob","mcp__qmd__status"]

QMD Doctor

Run a comprehensive health check on the qmd configuration for this project. Perform each check below in order and report results as [PASS], [FAIL], or [WARN]. At the end, summarize the total number of issues found.

Remediation Reference

For any failure, suggest the appropriate fix:

Failure	Fix
qmd binary not found	npm install -g @tobilu/qmd
.claude/qmd.json missing	Run /avinyc:qmd-configure
Missing project field	Run /avinyc:qmd-configure
Collection not in qmd index	Run /avinyc:qmd-configure
Collection naming mismatch	Run /avinyc:qmd-configure to rename
Git hook missing/wrong marker	Run /avinyc:qmd-configure and re-enable git hook
Git hook has old --index flag	Run /avinyc:qmd-configure and re-enable git hook
MCP server not responding	Run claude mcp add qmd -- qmd mcp or add qmd to .mcp.json
YAML config missing collection	Run /avinyc:qmd-configure

Checks

1. qmd binary

command -v qmd

[PASS] if found (print the path), [FAIL] if not.

2. Config file exists

Check if .claude/qmd.json exists using Read. If it does not exist, report [FAIL] and stop — remaining checks depend on it.

3. Valid JSON

Read .claude/qmd.json. If you can parse it as JSON, [PASS]. If the content is malformed, [FAIL] and stop.

4. Has "project" field

Check the parsed JSON has a non-empty project string. [PASS] or [FAIL].

5. Default index database

test -f "$HOME/.cache/qmd/index.sqlite" && echo "exists" || echo "missing"

[PASS] if exists, [FAIL] if missing.

6. Global config

test -f "$HOME/.config/qmd/index.yml" && echo "exists" || echo "missing"

[PASS] if exists, [FAIL] if missing.

7-9. Collection checks

For each key in the collections object:

7. Collection in qmd index:

qmd collection list

Check if the collection name appears in the output. [PASS] or [FAIL].

8. Naming convention: If the project name is set, check that the collection name starts with {project}_. [PASS] or [WARN].

9. YAML config entries

If ~/.config/qmd/index.yml exists, check that each collection name appears in it:

grep -F "{collection_name}:" "$HOME/.config/qmd/index.yml"

[PASS] or [FAIL] per collection.

10-11. Git hook checks (only if gitHook is true)

10. Check .git/hooks/post-commit exists. If it does, verify it contains the marker comment # qmd-auto-index:{project}. [PASS], [WARN] (marker mismatch), or [FAIL] (missing).

11. Check the hook does NOT contain the deprecated --index flag. [PASS] or [WARN].

12. MCP server connectivity

Try calling mcp__qmd__status. If it returns data, [PASS]. If the tool is not available or returns an error, [WARN] with message:

MCP server not configured or not responding. Search will fall back to CLI. Run claude mcp add qmd -- qmd mcp or add qmd to .mcp.json.

Output Format

Print each result on its own line:

[PASS] qmd binary found: /path/to/qmd
[PASS] .claude/qmd.json exists
[PASS] .claude/qmd.json is valid JSON
[PASS] Project name: myproject
[FAIL] Default index database missing: ~/.cache/qmd/index.sqlite
[WARN] MCP server not configured — search will use CLI fallback
...

N issue(s) found.

If all checks pass, end with: All checks passed.