Trim compass bearings: –limit and heading integration

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

Two changes to compass bearings to reduce the token footprint it imposes on each LLM session:

  1. --limit N flag: pass a per-command result cap so that fleet, sprint, journal, and backlog sections each return at most N items instead of the full list. A sensible default might be 5–10 entries per section; the flag lets the caller (or the skill) override it. Internally each bearings sub-call (compass fleet, compass sprint story, compass journal, etc.) would forward --limit to the underlying command where supported, or post-filter the output before returning it.
  2. Integrate compass heading: replace or augment the current "where can I go next" prose at the end of bearings output with the output of compass heading, which ranks candidate next work items from journal activity, fleet state, sprint state, and backlog buckets. This gives the LLM a single prioritised suggestion rather than a full dump of open work, and keeps the bearings output action-oriented.

The two changes are independent but ship well together: --limit shrinks the context used by the situational sections, and heading integration replaces the open-ended "what's next" section with a focused ranked list.

Why

compass bearings is the first thing an LLM session runs and its output lands verbatim in the context window. As the project grows (more stories, more sprint history, more fleet entries) bearings output is growing proportionally and consuming an increasing share of each session's token budget before any real work starts. The --limit flag gives callers a knob to cap this without losing the structure. The heading integration improves signal quality: today the "next" section is a raw list of open work; heading's ranked output is directly actionable.

References

  • projects/ores.compass/src/compass.py — bearings command implementation
  • doc/llm/skills/agile-find-bearings/SKILL.org — the skill that calls bearings at session start
  • Suggest the next work item to pick up — the heading story

See also

Emacs 29.1 (Org mode 9.6.6)