Standardise timeline bucket generation as a compass writer (for the snapshot skill)

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

Timeline buckets are currently hand/LLM-authored; compass timeline only has generate (lists changed docs), now, and show — there is no writer. Build the writer as part of the snapshot skill (snapshot-skill task), e.g. compass timeline bucket --from --to (or --window 20m --since). Logic, proven by the stopgap used to backfill the Sprint 20 timeline:

  1. Read compass timeline generate -f json{from,to,documents,prs} (local-time events; documents carry doc_type, action (created / updated / state with from=/=to), id, title).
  2. Slice into fixed windows (default 20 min); skip windows with no events (omit empty buckets — confirmed needed: 54 empties made the board chart unreadable).
  3. Per window, aggregate events per document id and emit the canonical sections the board parser expects (loadTimelineBuckets in projects/ores.org-js/agile/src/data.js counts rows of the first table under each): * Stories / * Tasks (| X | Event | Notes |), * Captures (| Capture | Notes |), * Pull requests (| PR | Event | Title |), plus * Summary, * Problems and suspicious decisions, * Audit. Event string = chained state transitions (BACKLOG → STARTED → DONE) else created / updated.
  4. Filename <YYYYMMDDTHHMM>-<YYYYMMDDTHHMM>.org; stable :ID: (reuse on regenerate). #+type: timeline.

The summary, problems, and audit prose is the genuinely LLM-curated part — the writer can scaffold counts/tables, the snapshot skill fills the narrative.

Why

Hand-rolled inline generation is not repeatable and drifts from the format the board parses (the first cut emitted a Documents section the board ignored, so only PRs rendered). A standard writer keeps buckets consistent with the parser and lets any session refresh the timeline with one command.

References

See also

Emacs 29.1 (Org mode 9.6.6)