How do I triage and promote captures?

Table of Contents

Captures land in the product backlog inbox (doc/agile/product_backlog/inbox/) and flow through triage buckets to become stories or tasks. Compass owns every move — never relocate capture files by hand, as promotion must preserve the capture's UUID (org-roam links point at it) and regenerate the backlog indexes.

Question

How do I triage an inbox capture into a backlog bucket, and how do I promote a capture into a story or task when work starts on it?

Answer

List what is in the inbox: 

./compass.sh inbox

Triage — move a capture into a bucket. next means shortlisted for an upcoming sprint, deferred means parked, discarded means rejected (kept for the record, not deleted): 

./compass.sh capture file <slug> next

Promote — when work starts, turn the capture into a story (or a task on an existing story). Promotion preserves the capture's UUID, carries its What/Why content over, creates the feature branch, removes the capture file, and regenerates the backlog indexes: 

./compass.sh capture promote <slug> --to story

./compass.sh capture promote <slug> --to task --story <id-or-slug>

If a capture was implemented directly without becoming a story (e.g. a small fix absorbed into an in-flight task), file it as discarded with a note rather than deleting it — the record of the idea and its resolution stays linkable.

Script

Tested by

Manual smoke test: compass capture --help output matches the commands above (verified 2026-06-06). No CI coverage yet.

See also

Emacs 29.1 (Org mode 9.6.6)