miller-search-debug

Miller Search Debug

Diagnose search behavior by checking the query mode, index freshness, projection limits, and whether the expected result exists.

Workflow

1. Reproduce the exact query:

search(query="<original>", limit=20)

2. Compare modes when the query intent is unclear:

search(query="<symbol-ish>", mode="symbol")
search(query="<path-ish>", mode="file")
search(query="<docs or prose>", mode="content")
search(query="<source body text>", mode="source")
search(query="<imported log text>", mode="external")
search(query="<imported web text>", mode="web")
search(query="<broad text>", mode="all-text")
search(query="<comment or literal>", regions="comment|string_literal|doc_comment")
search(query="<known area>", file_pattern="src/ui/**", language="typescript")

3. Check common beta gotchas:

• Natural-language search hides test code by default; use exclude_tests=false when tests are expected.
• Symbol search ranks name + signature; docs/prose belong in mode=content.
• Source bodies belong in mode=source; imported logs/reports and web markdown belong in mode=external or mode=web.
• Cross-workspace exact-text audits should use content search "<term>" --workspace-id all --kind source|docs|config|external_file|web.
• Comment, doc-comment, and string-literal searches require region indexing and a fresh sidecar.
• File/path queries should use mode=file when auto mode looks noisy.
• Scoped workflows should use file_pattern and language before raising limit.
• Stale indexes should be refreshed with workspace(operation="refresh").

4. Verify the expected item exists:

search(query="<exact symbol or file>", mode="auto", exclude_tests=false)
inspect(target="<expected-symbol-or-file>")

5. If the expected result is connected by calls rather than text, use:

trace(target="<nearby-symbol>")
context(query="<workflow around expected result>")

Report

Use this shape:

Search Debug: "<query>"
Expected: <symbol/file/text>

Observed:
- <top results or failure>

Diagnosis:
- <wrong mode, stale index, hidden tests, projection limit, region disabled, or true miss>

Next:
- <specific query, refresh, or implementation follow-up>

Do not widen Miller's symbol ranking as a first response. First prove that mode=content, regions=..., file mode, or refresh does not solve the workflow.