Task: Add scoped search to compass

Table of Contents

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:

  1. Added --under PATH (append) and --type DOCTYPE arguments to the search subparser.
  2. Increased the over-fetch cap from limit*10 (max 200) to limit*50 (max 1000) when either filter is active, so post-filter clipping still yields --limit hits from a large doc corpus.
  3. Applied --under as a post-filter using both Path.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).
  4. Applied --type as a post-filter: load the doc_index, collect UUIDs whose doctype matches, and keep only those results.
  5. 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.
  • --under is repeatable; --type accepts any doctype string.
  • The search recipe documents the backlog-only idiom with three examples.

Emacs 29.1 (Org mode 9.6.6)