Compass search: bucketed results by dimension
Table of Contents
This page is a capture in the inbox bucket of the product backlog — a pre-sprint idea, not yet pulled into a sprint as a story.
What
Restructure compass search output into three labelled buckets, each capped
at N results (default 5, overridable with --limit):
- Recipes — matches inside
doc/recipes/only. Label: "How do I…" — the answer to a procedural question. Shown first because it is what the caller most often wants. - Now — matches everywhere except
doc/agile/versions/(knowledge docs, skills, runbooks, component overviews, captures, backlog). Label: "What is this / where is it now?" — live project knowledge and current state. - Historic — matches inside
doc/agile/versions/only (sprint stories, tasks, retrospectives). Label: "Have I seen this before?" — past sprint artefacts; useful for context but rarely the primary target of a search.
Each bucket is introduced by its label line before the hits, and the total count per bucket is shown so the caller knows whether the cap truncated results (e.g. "Recipes (3/3)" vs "Historic (5/47)"). The existing ranking (score, recency, type boost) applies within each bucket independently.
Why
Today compass search returns a single ranked list. Historic agile artefacts
(closed stories, old sprint tasks) accumulate over time and frequently
outscore current knowledge docs and recipes because they contain the same
keywords in denser context. The result is that a search for e.g. "commission
currency" returns twenty closed sprint_20 task files before the live
commission_currency story or the relevant recipe. The bucketed layout
eliminates this by giving recipes and live knowledge guaranteed top slots
regardless of the historic hit count. The label lines also help an LLM caller
interpret what kind of result it is reading without inspecting the path.
References
projects/ores.compass/src/compass.py— search command implementation (cmd_search, result ranking and formatting)- Trim compass bearings: –limit and heading integration — related capture; bearings also suffers from result volume and uses the same search index