Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(answer): serve substance on the gated low-confidence path; unpin cached misses (#887)

Swati Ahuja50748aff4b5a
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
index 492ec6207..b6aac06e6 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
@@ -113,6 +113,7 @@ from repowise.server.mcp_server.tool_answer.retrieval import (
_apply_domain_penalty,
_candidate_justification,
_downweight_deterministic,
+ _enrich_gated_excerpts,
_intersection_boost,
_rerank_by_coverage,
)
@@ -472,6 +473,12 @@ async def get_answer(
# promotion, source-body excerpts). Give synthesis another shot
# with the new context rather than pinning the bad answer.
hedged_cache = _answer_is_hedged(payload.get("answer", ""))
+ # Bypass-on-empty: older versions cached gated (empty-answer)
+ # payloads, so a retrieval miss got pinned until TTL and every
+ # later improvement to the miss path was invisible. The write
+ # side no longer caches empty answers; this read-side check
+ # retires rows that predate that fix.
+ empty_cache = not (payload.get("answer") or "").strip()
# A row cached before exclude_patterns changed may reference a
# now-excluded file — in its fields or its prose. Re-synthesize
# rather than scrub the fields and leave the prose dangling.
@@ -503,6 +510,8 @@ async def get_answer(
)
elif hedged_cache:
_log.info("Bypassing hedged cache entry for re-synthesis")
+ elif empty_cache:
+ _log.info("Bypassing cached empty-answer (gated) entry")
elif excluded_cache:
_log.info("Bypassing cache entry referencing a now-excluded path")
elif stale_commit:
@@ -784,6 +793,17 @@ async def get_answer(
dominant = (top_score / second_score) >= _DOMINANCE_RATIO
if not dominant:
+ # Attach real page content to the top candidates before shaping
+ # the reply. Agent-transcript evidence (context-tool bench,
+ # 2026-07-17): a pointers-only gated payload sends the agent into
+ # an 8-15 call Grep/Read spree that costs more than a bare agent —
+ # it paid for the tool call and still had to acquire all content
+ # natively. Excerpts turn the miss path into "pick one candidate,
+ # verify with at most one Read". (The 2026-07-11 dogfood dropped
+ # the per-hit key_symbols METADATA dump as unused; readable
+ # content is the part that was worth keeping.)
+ with contextlib.suppress(Exception):
+ await _enrich_gated_excerpts(hits, ctx)
# Structured candidate set: a decision-shaped list with a
# one-line justification per file. Beats the prior flat
# ``fallback_targets`` list because the agent can pick ONE file
@@ -794,6 +814,7 @@ async def get_answer(
"why_relevant": _candidate_justification(h),
"score": round(h.get("score", 0.0), 3),
"domain_penalty": h.get("_domain_penalty"),
+ **({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),
}
for h in hits[:_GATED_RETURN_HITS]
if h.get("target_path")
@@ -801,13 +822,7 @@ async def get_answer(
# Mine source comments for rationale the wiki/decision corpus
# missed — turns "go Read these 5 files" into a cited why.
code_rationale = _gather_code_rationale(ctx, hits, fallback_targets, question)
- # A miss should be cheap to READ, not just cheap to ignore. The old
- # gated payload also carried a full per-hit key_symbols dump — the
- # single largest block by volume — that duplicated best_guesses and
- # went unused (2026-07-11 dogfood). best_guesses (file + one-line
- # why + score) and code_rationale carry the choosing signal; the
- # symbol dump does not. Drop it, and skip the excerpt-enrichment DB
- # round-trip that only fed it (a small latency win on the miss path).
+ has_excerpts = any("excerpt" in g for g in best_guesses)
gated: dict = {
"answer": "",
"citations": [],
@@ -815,8 +830,15 @@ async def get_answer(
"retrieval_quality": "weak",
"best_guesses": best_guesses,
"next_action_hint": (
- f"Read {best_guesses[0]['file']} first — it scored highest "
- "but retrieval was ambiguous, so verify before answering."
+ (
+ f"Start from the excerpt of {best_guesses[0]['file']} — "
+ "it scored highest; Read the file only to verify "
+ "details the excerpt does not settle."
+ if has_excerpts
+ else f"Read {best_guesses[0]['file']} first — it scored "
+ "highest but retrieval was ambiguous, so verify "
+ "before answering."
+ )
if best_guesses
else (
'Retry search_codebase with mode="symbol" or '
@@ -829,7 +851,12 @@ async def get_answer(
"note": (
"Multiple plausible candidates — synthesis skipped to "
"avoid anchoring on a wrong frame. Each best_guess entry "
- "names why that file is in the running."
+ "names why that file is in the running"
+ + (
+ ", and its excerpt carries that page's actual content."
+ if has_excerpts
+ else "."
+ )
),
}
if code_rationale:
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
index ab858977d..cce20805b 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
@@ -176,8 +176,12 @@ _HEDGE_MARKERS = (
# When the gate triggers and we drop synthesis, fetch this many chars of
# real page content per top hit so the agent has substantive raw material
-# to ground in (vs. one-line summary that's too thin to act on).
-_GATED_EXCERPT_CHARS = 600
+# to ground in (vs. one-line summary that's too thin to act on). 1500 chars
+# is enough for a page's opening section plus a code reference; at 600 the
+# excerpt stopped mid-context and agents fell back to native exploration
+# anyway (context-tool bench transcripts, 2026-07-17). Three hits at 1500
+# chars is ~1.1k tokens — well under any MCP output budget.
+_GATED_EXCERPT_CHARS = 1500
_GATED_RETURN_HITS = 3
# Path-prefix domain heuristics — down-weight cross-domain retrievals so a
@@ -287,7 +291,7 @@ _HIGH_CONFIDENCE_SCORE_FLOOR = 1.5
# v7: concept anchoring - number-bearing why/value questions anchor the file
# whose comment justifies the number and surface that comment as code_rationale
# even on the high path. Cached v6 payloads predate the anchor + surfacing.
-_ANSWER_SCHEMA_VERSION = 7
+_ANSWER_SCHEMA_VERSION = 8
# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's
# stamped ``_indexed_commit`` vs the repo's current head) is the primary
diff --git a/tests/unit/server/mcp/test_answer_cache.py b/tests/unit/server/mcp/test_answer_cache.py
index f95c1acb1..1ad12999e 100644
--- a/tests/unit/server/mcp/test_answer_cache.py
+++ b/tests/unit/server/mcp/test_answer_cache.py
@@ -105,6 +105,48 @@ async def test_hedged_row_is_upgraded_on_resynthesis(setup_mcp, factory, monkeyp
assert "_indexed_commit" not in third
+async def test_cached_empty_answer_row_is_bypassed(setup_mcp, factory, session, monkeypatch):
+ """A legacy cached gated payload (empty answer) never serves from cache.
+
+ Older versions cached the gated best_guesses payload, pinning a retrieval
+ miss until TTL and hiding every later improvement to the miss path. The
+ write side no longer stores empty answers; the read side must retire the
+ rows that predate that fix.
+ """
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+ from repowise.server.mcp_server.tool_answer.answer import _hash_question
+ from repowise.server.mcp_server.tool_answer.config import _ANSWER_SCHEMA_VERSION
+
+ _patch_retrieval(monkeypatch, answer_mod)
+
+ res = await session.execute(select(Repository))
+ repo = res.scalars().first()
+ # Legacy row: current schema version (so the schema gate passes) but the
+ # old empty-answer gated shape.
+ session.add(AnswerCache(
+ repository_id=repo.id,
+ question_hash=_hash_question(QUESTION),
+ question=QUESTION,
+ payload_json=_json.dumps({
+ "answer": "",
+ "confidence": "low",
+ "fallback_targets": ["src/auth/service.py"],
+ "_schema_version": _ANSWER_SCHEMA_VERSION,
+ }),
+ provider_name="mock",
+ model_name="mock-1",
+ ))
+ await session.commit()
+
+ direct = _Provider("Auth flows through src/auth/service.py via AuthService.check().")
+ _patch_provider(monkeypatch, answer_mod, direct)
+ result = await get_answer(QUESTION)
+ assert direct.calls == 1, "empty-answer cache row must be bypassed"
+ assert "AuthService.check" in result["answer"]
+
+
@pytest.mark.asyncio
async def test_cache_bypassed_when_indexed_commit_changes(setup_mcp, factory, session, monkeypatch):
"""A row stamped at commit A is bypassed once the repo is indexed at B."""
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
index 66c06d9e0..d9c8e064d 100644
--- a/tests/unit/server/mcp/test_answer_calibration.py
+++ b/tests/unit/server/mcp/test_answer_calibration.py
@@ -878,6 +878,54 @@ async def test_gated_answer_surfaces_code_rationale(setup_mcp, monkeypatch, tmp_
assert any("OOMs" in r["comment"] for r in result["code_rationale"])
+async def test_gated_answer_carries_candidate_excerpts(setup_mcp, monkeypatch, tmp_path):
+ """Gated path serves page content inline, not just pointers.
+
+ A pointers-only miss payload makes the agent re-acquire all content
+ natively (observed as an 8-15 call Grep/Read spree in agent transcripts),
+ so the gated reply must carry the top candidates' actual page content and
+ say so in its guidance text.
+ """
+ import repowise.server.mcp_server as mcp_mod
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ async def _fake_retrieve(question, ctx):
+ return [
+ {"page_id": "file_page:pkg/alpha/one.py", "score": 4.0},
+ {"page_id": "file_page:pkg/alpha/two.py", "score": 3.8},
+ ]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for h in hits:
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = "Module summary."
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ return hits
+
+ async def _fake_excerpts(hits, ctx=None):
+ for h in hits:
+ h["excerpt"] = f"Page content for {h['target_path']}: chunking rationale..."
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+ monkeypatch.setattr(answer_mod, "_enrich_gated_excerpts", _fake_excerpts)
+ (tmp_path / "pkg" / "alpha").mkdir(parents=True)
+ (tmp_path / "pkg" / "alpha" / "one.py").write_text("CHUNK = 8\n", encoding="utf-8")
+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))
+
+ result = await get_answer("why do uploads chunk at 8mb")
+ assert result["confidence"] == "low"
+ top = result["best_guesses"][0]
+ assert top["excerpt"].startswith("Page content for pkg/alpha/one.py")
+ # Guidance must direct the agent at the excerpt, not at a blind Read.
+ assert "excerpt" in result["next_action_hint"]
+ assert "excerpt" in result["note"]
+
+
# ---------------------------------------------------------------------------
# Frame-grounding gate — a why-answer naming a mechanism term absent from the
# retrieved source is downgraded from high to medium (conflated rationale).