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

91 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
type: decision
tldr: 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.
status: accepted
decided_on: 2026-10-21
decided_by: Michał Kopeć
affects: AGENTS.md, ckb.yaml, .agents/skills/ckb-add-conversation/, .agents/skills/ckb-routine/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, docs/MANUAL.md
confidence: 0.85
quality: 0.8
last_updated: 2026-10-21
freshness_window_days: 365
retention: 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](0006-title-chosen-by-agent.md). 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.