ckb/docs/decisions/0009-session-start-in-one-call.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

3.1 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Session start is one script call whose output tells the agent what to act on; the always-loaded prompt describes the command, not the five checks, and no longer reads wiki/index.md or the whole workload file. accepted 2026-10-29 Michał Kopeć AGENTS.md, .agents/skills/ckb-lint/scripts/session_start.py, .agents/skills/*/SKILL.md, tests/smoke.sh 0.85 0.8 2026-10-29 365 high

D-0009 — Session start in one call, and skills say only what their description does not

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

Context

A session cost about 9k tokens before the first question was read: AGENTS.md (19k characters, 4.2k of them Rule E's description of five commands and what to do with each), twenty skill descriptions, wiki/index.md, the whole latest workload/ file, and three to five tool round-trips for the checks. On trigger, every skill opened with a ## Purpose section that mostly restated the description already in context. These costs were paid on every session and every skill use, and none of them bought accuracy.

Decision

  1. ckb-lint/scripts/session_start.py performs Rule E's start in one call: identity, title (stored unless already set), announce_title, git status, lint_report.py --quick, autosave_hook.py --check only when the switch or a hook file exists, routines.py --due, and the last ## block of the latest workload/ note (by filename date, ties by mtime). Each line says what action it calls for; clean lines call for none. The wrapped scripts keep their own interfaces.
  2. Rule E in AGENTS.md names the command and the action per output line. The no-Python fallback stays as before (lint_quick.sh/.ps1 plus the git and workload steps by hand, routine check skipped).
  3. wiki/index.md is not read at session start. Index-first navigation already starts there for KB questions, and the twelve skills that need the index read it themselves.
  4. A skill's ## Purpose holds only what its description does not say: the invariants (what it writes and never touches), the design framing a step needs, and the scope boundaries. Restating the trigger phrases or the one-line job is dropped.
  5. Rule B's log-entry format lives in AGENTS.md only; no skill repeats it.

Consequences

  • One tool call and one short block per session start; the workload tail stays bounded as the file grows.
  • The index is read exactly once, by the skill that uses it.
  • Measured at the time: Rule E 4.2k → 3.0k characters; ## Purpose 16.2k → 7.8k across the skills, up to 1.9k saved per trigger for ckb-index-external and ckb-retrieve.
  • Not changed, because each carries a trade-off: the skill descriptions (shorter ones trigger less reliably), the routing table in AGENTS.md (agents other than Claude Code have no skill listing), the page-body section contract (four skills would have to load it on trigger), and the size of ckb-upgrade/ckb-init (splitting rarely-run steps into references adds a read exactly when they run).