ckb/docs/decisions/0005-session-titles-and-routines.md
Michał Kopeć 6c49063ecb Template 1.16.1: agent picks the session title, first reply only announces it
announce_title replaces ask_title; no question, no waiting. D-0006 reverses
point 1 of D-0005.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-24 15:57:12 +02:00

4.6 KiB
Raw Blame History

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision A new session opens by asking for its title and waits for the answer; routines are repo-level, time-since-last actions declared in ckb.yaml, fired at session start after the user's request, with the last-run date committed so one person's run counts for everyone. accepted 2026-10-21 Michał Kopeć AGENTS.md, ckb.yaml, .agents/skills/ckb-add-conversation/, .agents/skills/ckb-routine/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, docs/MANUAL.md 0.85 0.8 2026-10-21 365 high

D-0005 — Sessions are named up front; routines are time-since-last and shared

Status: Accepted · Decided: 2026-10-21 · Deciders: Michał Kopeć

Point 1 (ask for the title and wait) was reversed three days later by D-0006. Points 2–5 stand.

Context

Saved conversations (1.12.0) and workload notes were named from Claude Code's own AI title or the first user line, which produced names like "ckb-reset" or "Commit first, clean everything". Separately, maintenance that should happen regularly (lint, re-indexing an external source) happened only when somebody remembered to ask, and nothing in the template could express "do this every week".

Decision

  1. Ask for the title first, and wait. When conversations.ask_title is true (the default), the first reply of a new session is the single question "What should this conversation be called?" and no work starts until it is answered. The title is stored per machine (tmp/conversation-titles/<session-id>.title, via save_conversation.py --set-title) so the autosave Stop hook and every later save use it; it names the saved transcript and the workload block. A first message that already names a title, a resumed session with a stored title, and a non-interactive run skip the question.
  2. Routines are declared in ckb.yaml, one item per routine with name, do (a routing-table phrase, executed as if the user had said it), every (Nh|Nd|Nw), confirm and last_run. A new skill, ckb-routine, owns the block through a script that edits only the routine's own lines.
  3. Due routines run after the user's request, in the same turn. The session-start check (routines.py --due) only collects them; the user's first request is answered first, then each due routine runs and is reported in one line. confirm: true turns that into a question at the end of the reply. Only a completed action is marked; a failed or declined one returns next session. A manual run of the same action also marks the routine.
  4. last_run is committed, so a routine fires once per period for the whole repo, not once per clone. The trade-off is an occasional one-line merge conflict when two people fire the same routine on different days; the later date wins.
  5. ckb-reset and ckb-sync-changes cannot be routines: one is destructive, the other touches the remote.

Alternatives considered

  • Ask the title inline and keep working. Cheaper by one round-trip, but the first turn's work would be saved under a derived title until the answer arrived, and the hook would have already written files under the wrong slug. The user chose the hard ask.
  • Run due routines before the first request. Simplest rule, but a slow routine (ingest, external index) would sit between the user and their answer.
  • Always ask before running a routine. Not automatic; kept as the per-routine confirm option instead.
  • Per-machine routine state under tmp/. Would make a weekly lint run once per clone per week; the repo is what needs linting, not the clone.
  • Derive the last run from wiki/log.md. Fragile: not every action writes to the wiki log, and parsing free-text Source: lines to decide whether to run something is guesswork.
  • Claude Code's cloud scheduler / /loop. Needs a running agent and lives outside the repo, so it is neither shared nor offline. Documented as a different tool, not a replacement.

Consequences

  • ckb.yaml gains conversations.ask_title and routines:; ckb-init writes both, ckb-upgrade and ckb-module leave them as found.
  • Rule E grows two steps (the title question first, the routine check last). Without Python the routine check is skipped, consistent with D-0003.
  • The smoke test covers --set-title (slug and heading follow the stored title, the old pair is removed) and routines.py (--due golden output, --mark/--add/--remove touch only the expected lines).
  • Schema stays 1.5: no page field changes.