Task: Add scoped search to compass
This page documents a task in the Compass quality of life story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Hunting for product-backlog captures exposed three search gaps: compass search has no path scoping (no –under like compass list), so historic-sprint docs drown out backlog hits; compass list –under scopes by path but matches title/description only, leaving body-only mentions invisible; and search has no –type filter. Add –under (repeatable) and –type to compass search so full-text queries can be scoped (e.g. compass search –under doc/agile/product_backlog –type capture 'ores-shell'), and document the backlog-search idiom in the search recipe.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Compass quality of life |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | None. |
| Last touched | 2026-06-10 |
Acceptance
- compass search –under <path> restricts full-text hits to docs below the path (repeatable).
- compass search –type <doctype> filters by document type.
- The search recipe shows the backlog-only idiom; searching 'ores-shell scripts' over the backlog finds captures by body text without grep.
Plan
Modified projects/ores.compass/src/compass.py and
doc/recipes/compass/how_do_i_search_docs_with_compass.org:
- Added
--under PATH(append) and--type DOCTYPEarguments to thesearchsubparser. - Increased the over-fetch cap from
limit*10(max 200) tolimit*50(max 1000) when either filter is active, so post-filter clipping still yields--limithits from a large doc corpus. - Applied
--underas a post-filter using bothPath.relative_to(PROJECT_ROOT)and a path-component suffix check (needed because the FTS index stores absolute paths that may use a different mount prefix than the current shell). - Applied
--typeas a post-filter: load the doc_index, collect UUIDs whosedoctypematches, and keep only those results. - Updated the search recipe with three worked examples showing the backlog-only idiom.
Notes
PRs
| PR | Title |
|---|---|
| #1234 | [compass] Add scoped search (–under/–type); fix capture promote placeholders |
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
Result
All acceptance criteria met:
compass search --under doc/agile/product_backlog --type capture 'ores-shell'returns only product-backlog captures matching the query.--underis repeatable;--typeaccepts any doctype string.- The search recipe documents the backlog-only idiom with three examples.