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):

  1. 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.
  2. 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.
  3. 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

See also

Emacs 29.1 (Org mode 9.6.6)