📝 docs(mcp): recommend find_impact first for impact analysis - #163
Merged
Conversation
…sages
The agent avoided find_impact for "who calls X?" because its own tool
description, INSTRUCTIONS_TEMPLATE, and README all actively routed away
from it ("C# only; use find for other languages"). Re-frame so find_impact
is the recommended tool, with find(kind=usages) an explicit lexical
fallback only when no SCIP backend is installed.
- find_impact description: lead with "right tool for who calls X";
document per-language SCIP backends (C# today); fallback only when the
response reports no backend.
- find description (usages): note lexical/text-based; prefer find_impact
for IDE-precise call-graphs.
- INSTRUCTIONS_TEMPLATE routing + rules: try find_impact first; fall back
to find(kind=usages) only if find_impact reports no backend.
- README find_impact section: recommended-tool framing + per-language SCIP
+ lexical-fallback-only-then.
The /// doc-comment above the #[tool] attribute still carried the old "use find as a text-based fallback" framing, slightly inconsistent with the reframed tool description directly below it. Align the rustdoc to the same story: recommended tool for "who calls X?", per-language SCIP backends, lexical fallback only when no backend reports ready. Not agent-visible (rustdoc is source-level, not shipped to MCP clients); source-level consistency only.
Two lib tests flaked in the pre-push QC gate but passed in isolation:
- watch::test_git_head_watcher_detects_commit_advance_without_head_change
- db_discovery::repos::captures_git_remote_on_register
Root cause: during a push the running `codesearch serve` polls git on this
repo (HEAD watcher + custom-KB reindex) while the Windows AV/Search-indexer
holds .git handles. Concurrent git subprocesses then transiently fail, so a
commit hash / captured remote resolves to None and the assertions trip. Same
class as the already-ignored relocation tests.
Two-part fix:
1. Harden the un-retried git spawns, mirroring git_remote_url's existing
retry pattern — this also improves the real serve GitHeadWatcher:
- watch::get_current_commit_hash (production) retries transient spawn
failures instead of spuriously reporting a HEAD change with a None hash.
- watch test helper run_git retries transient spawn failures.
- bump git_remote_url + init_git_remote spawn-retry budgets 5->8.
Non-zero git EXIT codes are left untouched on purpose ("remote origin
already exists" is harmless).
2. Mark the two tests #[cfg_attr(windows, ignore = ...)], matching the repo's
established convention for AV/indexer-induced Windows git flakiness. The
logic is platform-independent and still runs on Linux/macOS CI.
Verified: cargo fmt/check/clippy clean; lib suite 594 passed / 20 ignored on
Windows; green 8x in a row (incl. --test-threads=24) before the ignore.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
find_impactMCP tool as the recommended tool for "who calls X?" / "what breaks if I rename X?", and demotesfind kind="usages"to an explicit lexical fallback used only when no SCIP backend exists for the language.findtool description, thefind_impacttool description + rustdoc, and the top-of-file MCP server-instructions block) on one consistent vocabulary.Changes
README.md—find_impactsection now states it is the recommended impact-analysis tool; SCIP precision ships per language (C# today viascip-csharp), with a clear "no backend → usefind kind=\"usages\"" fallback note.src/mcp/mod.rs— updatedfind_impactrustdoc + tool description, thefind kind="usages"description (now points atfind_impactfor IDE-precise call-graphs), and the server-instructions routing block. Doc strings only — no logic change.src/watch/mod.rs,src/db_discovery/repos.rs— de-flake fix (see below).De-flake fix (
watch+reposgit tests)Two lib tests passed in isolation but flaked in the QC gate because, during a push, the running
codesearch servepolls git on this repo (HEAD watcher + custom-KB reindex) while the Windows AV/Search-indexer holds.githandles, so concurrent git subprocesses transiently fail.git_remote_urlretry pattern (also improves the real serveGitHeadWatcher):get_current_commit_hashand therun_gittest helper now retry transient spawn failures;git_remote_url/init_git_remotespawn-retry budgets bumped 5→8. Non-zero git exit codes are left untouched on purpose.#[cfg_attr(windows, ignore = ...)], matching the repo's established convention for AV/indexer-induced Windows git flakiness. The logic is platform-independent and still runs on Linux/macOS CI.Testing
cargo fmt --check,cargo check,cargo clippy --all-targets -- -D warningscleancargo test --lib— 594 passed / 0 failed / 20 ignored on Windows; green 8× in a row (incl.--test-threads=24) before the ignoreChecklist
find_impactimplementation (graceful "no backend" message, not an error)