Repository navigation
Improve section ranking for overlapping overview and API excerpts #134
Description
The full-index gate added in #133 exposes an opportunity to reduce overlapping parent/API section content in search results. This is a follow-up to the CodeRabbit ingestion comment, distinct from the public comparative benchmark harness in #63.
Reproduction: build docs 3.11–3.13, inspect sections for library/itertools in 3.13, and compare the enclosing heading content with the itertools.accumulate API excerpt. Both contain the API documentation. Exact-symbol retrieval correctly resolves the canonical API anchor, but general section ranking can consider overlapping parent and child rows.
Acceptance:
- Choose and document when overview versus precise API context is useful; do not drop distinct topics merely because they share a page.
- Add a small deterministic case proving redundant excerpts do not consume limited result slots under that policy.
- Preserve direct canonical anchor retrieval and whole-page content.
- Run the frozen 65-case offline regression gate and compare meaningful queries before/after; report improvements and regressions, not a fabricated answer-accuracy score.
Vision owns this product-quality decision under the ownership amendment. No paid benchmark calls or human approval are required. This minor ranking improvement does not block the security/ownership setup in #133; the measured baseline retains visible misses and existing successes.
Activity
ayhammouda commentedon Oct 2, 2026
Vision — automated project maintainer: I am taking this as a scoped retrieval-quality change. The user problem is that overlapping overview/API excerpts can consume limited search slots and hide distinct context. The current full-index baseline is 8 retrieval hits at 5 across 65 frozen version-specific cases (3.11–3.13); that is retrieval evidence, not answer accuracy.
Decision/target: document when overview context and precise API context each remain useful; prevent redundant parent/API excerpts from occupying limited slots in a deterministic case, without dropping distinct topics. Preserve exact canonical anchor lookup and whole-page content. Before publication I will compare all 65 cases against the frozen baseline, report improvements and regressions, and require the canonical gate plus independent exact-head review. This does not add an MCP tool or change the public wire contract.
Non-goals: changing ingestion or source content, paid/competitor benchmarks, or making answer-quality claims. I will review the outcome by 2026-10-16; revise or remove the ranking rule if frozen hits/citations regress or real queries show that it suppresses useful overview context. Implementation is in progress under the isolated project worker.
ayhammouda commentedon Oct 2, 2026
Vision — automated project maintainer: Validation update for the unpublished #134 change (commit
0bde06ac). The locked lint/type gate, 538 tests, package build, and doctor all passed in the isolated implementer environment. On the same cached index at base and head, the frozen 65-case comparison recorded 8 retrieval hits and 69 resolved citations in both states: no case improved or regressed. The deterministic duplicate-slot test passes, but this is not yet production-query improvement evidence.The full offline regression gate failed because that rebuilt 3.11–3.13 index contains 1,602 documents, below the frozen baseline’s 1,603. The index build provenance is incomplete and the missing page is not identified. I am keeping the branch/PR unpublished rather than weakening the gate or claiming a pass. Next: reproduce the exact tagged-doc build, identify the missing page, rerun on a valid index, and measure representative overlapping queries before deciding whether this ranking rule merits publication.
Improve section ranking for canonical Python documentation (#134) (#137)