Rotate Timeline

The Rotate Timeline block replaces the todos shown in a custom timeline with fresh candidates. The previous picks move into the timeline's rotation history (stored in its excluded-todos list, capped at 200 entries) so they are not repeated on later rotations. When the candidate pool runs dry, the oldest history entries are recycled so the timeline is never empty. Todos are never deleted — only which ones the timeline shows changes.

Pair it with a daily Schedule trigger to power "N fresh things every morning" timelines (e.g. "5 Experiences Every Day").

Block Type

kaizen_rotate_timeline

Input Fields

Field	Description
Timeline	Custom timeline to rotate. Use the timeline ID from a Create Timeline block output or your timeline list (not the share link ID). Built-in timelines (Home, Following, Personal) cannot be rotated.
Todos per rotation	How many todos to show after the rotation. Default 5.
Candidate Todos (optional)	Explicit candidates or a reference like `<kaizen_todos_1.todoIds>`. When set, the source pool below is not queried — use this to feed picks from a Kaizen Todos or AI block.
Source	Public pool (default) — platform-wide public todos. My todos — the workflow owner's own todos (e.g. a personal backlog; the featured filter never applies here).
Source Buckets (optional)	Restrict candidates to these buckets. Leave empty for the scope-wide pool.
Source Tags (optional)	Restrict candidates to todos carrying any of these tags.
Status Filter	Only todos with this status qualify (Any / Not Completed / In Progress).
Schedule Filter	Unscheduled only limits candidates to todos without a schedule — a true backlog.
Location Filter	Near my saved location restricts candidates to todos within the radius of your saved location (Settings → Location). Fails with a clear error when no location is saved.
Radius (km)	Radius for the location filter. Default 40 km.
Pick Order	Random (default), Oldest updated first (stale-first — walks the whole pool systematically across rotations), or Newest created first.
Pool Preference	Public pool only: Featured first (recommended) — prefer featured todos, falling back to the broader public pool on shortfall. Any public todos — draw from the whole public pool directly.

Outputs

Output	Type	Description
`timelineId`	string	ID of the rotated timeline
`addedTodoIds`	json	Todo IDs now shown in the timeline
`removedTodoIds`	json	Todo IDs moved out of the timeline into history
`recycledTodoIds`	json	IDs reused from history because fresh candidates ran short
`summary`	string	Human-readable rotation summary
`success`	boolean	Whether the rotation succeeded

How rotation works

The timeline's current filters are read; its includedTodoIds are the currently shown todos and its excludedTodoIds act as the no-repeat history.
Fresh candidates are gathered (featured/public pool, buckets/tags, or the supplied candidate list), excluding everything already shown or in history.
The new picks replace includedTodoIds; the previous picks are appended to the history, which is capped at its 200 newest entries.
On shortfall, the oldest history entries (then, as a last resort, the current picks) are recycled — a repeated day beats an empty timeline.

The rotation rewrites the timeline's full filter set with only the included/excluded todo lists changed — all other timeline filters (tags, buckets, dates, sorting) are preserved as-is.

Example: 5 fresh experiences every morning

Schedule trigger — daily at 7:00 AM (your timezone).
Rotate Timeline — your "5 Experiences Every Day" timeline, count 5, Featured first.

Deploy the workflow so the schedule executes the deployed version.

Example: daily 3 from your own backlog

Schedule trigger — daily at 7:00 AM (your timezone).
Rotate Timeline — count 3, Source = My todos, Status = Not Completed, Pick Order = Oldest updated first.

Stale-first plus the no-repeat history means the rotation works through your entire backlog before anything repeats.