Story: Compass CLI UX redesign

Goal
- Proposed taxonomy (to be validated in Task 1)
Status
Acceptance
Tasks
Decisions
Out of scope

This page documents a story in Sprint 19. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

Goal

ores.compass started as an orientation tool but has grown into a full developer toolkit — scaffolding, capture, journal, backlog, and fleet management alongside the original orientation commands. Two problems have emerged:

Misleading description. The tool still calls itself "a repository orientation tool" in its docstring and --help output. New contributors (and LLMs) underestimate its scope.
Inconsistent UX. Commands are named by verb (goto, add, where, fleet) or by noun (journal, capture, inbox). Adding compass sprint or compass story commands without a taxonomy creates a third naming convention and paints future development into a corner.
Missing orient commands. There is no way to get a status snapshot of the current sprint (all stories by state) or of a story (all tasks by state). compass where only shows STARTED items.

This story:

defines the full noun-based command taxonomy through a System 2 UX analysis
fixes the tool description and organises --help by pillar
implements compass sprint status and compass story status
writes a recipe for the new orient commands
establishes backward-compatibility rules (aliases, deprecation warnings) so existing scripts and skills are not silently broken

Proposed taxonomy (to be validated in Task 1)

compass orient           # pillar header (existing commands keep their names)
  where                  # current version/sprint/in-flight (existing)
  fleet                  # worktree status via journal (existing)

compass sprint           # sprint-level operations
  status                 # all stories in current sprint, grouped by state (NEW)
  new                    # open a new sprint (currently: how_do_i_open_a_new_sprint recipe)
  close                  # close a sprint

compass story            # story-level operations
  status <id>            # all tasks in story, grouped by state (NEW)
  new                    # create a story (currently: compass goto --slug)
  start <id>             # mark story STARTED
  close <id>             # mark story DONE

compass task             # task-level operations
  new                    # create a task (currently: compass goto --story)
  start <id>             # mark task STARTED
  close <id>             # mark task DONE

compass journal          # session journal (existing)
  update / where / log

compass capture          # file a capture (existing)
compass backlog          # backlog buckets (existing)
compass search           # full-text search (existing)
compass list             # doc listing (existing)
compass show             # single doc detail (existing)

The Task 1 analysis will determine which verbs (goto, add) become aliases and whether backward-incompatible renames need a deprecation period.

Status

Field	Value
State	DONE
Parent sprint	Sprint 19
Now	Nothing.
Waiting on	Nothing.
Next	Done. All tasks complete.
Last touched	2026-06-01

Acceptance

A UX analysis document records the full command taxonomy, backward-compat decisions, and pillar organisation.
compass --help describes the tool as a "developer toolkit" (not "orientation tool") and lists subcommands grouped by pillar.
compass sprint status prints all stories in the current sprint grouped by state (DONE / STARTED / BACKLOG) with task counts.
compass story status <id> prints all tasks in a story grouped by state, with branch and PR per task.
A recipe documents compass sprint status and compass story status, linked from the agile recipe index.
Existing commands (goto, add, where, fleet, capture, journal, backlog, search, list, show) continue to work unchanged (aliases or retained names per taxonomy decision).
All compass references in doc/recipes/, doc/llm/skills/, and doc/llm/runbooks/ are consistent with the new taxonomy and description. No recipe or skill refers to a renamed command without also documenting the alias.
CI passes. Site builds cleanly.

Tasks

Task	State	Start	End	Description
Compass CLI UX analysis and taxonomy	DONE	2026-05-31	2026-06-01	System 2 analysis: full command taxonomy, pillar organisation, backward-compat rules, description fix.
Fix compass description and organise –help by pillar	DONE	2026-06-01	2026-06-01	Update module docstring; add pillar epilog to –help output.
Implement compass sprint status	DONE	2026-06-01	2026-06-01	All stories in current sprint grouped by state with task counts; reads story.org directly.
Implement compass story status	DONE	2026-06-01	2026-06-01	All tasks in a story grouped by state, with branch and PR per task.
Load SSH_AUTH_SOCK from .env in compass.sh	ABANDONED		2026-06-05	Add SSH_AUTH_SOCK to .env; update compass.sh to source .env so git operations work without manual export.
Write recipe for new orient commands	DONE	2026-06-01	2026-06-01	Recipe for compass sprint status and compass story status; wire into agile recipe index.
Audit and update compass recipes, skills, and runbooks	DONE	2026-06-01	2026-06-01	Review all 34 compass references; update for new taxonomy and description.
Show blocked story dependency tree in compass where	ABANDONED		2026-06-05	Extend compass where to display blocked story chains as a tree in the Orient pillar.

Decisions

Task 1 gates all implementation. No code changes until the taxonomy and backward-compat decisions are recorded and agreed.
--uuids flag is a consistent convention. compass sprint status --uuids, compass story status --uuids (T4), and any future listing command show the full UUID of each item as a bracketed suffix. The full UUID is shown (not a prefix) so it can be copied and passed directly to compass story status, compass show, or any other command that accepts a UUID or UUID prefix. The flag name --uuids is standardised across all listing commands.

Out of scope

Implementing compass sprint new/close or compass story new/start/close in this story — those are follow-on stories once the taxonomy is agreed.
Renaming the ores.compass project or Python package.
Removing any existing command names — aliases only, no hard breakage.