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:
--limit Nflag: 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--limitto the underlying command where supported, or post-filter the output before returning it.- Integrate
compass heading: replace or augment the current "where can I go next" prose at the end of bearings output with the output ofcompass 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 implementationdoc/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