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

63 lines
3.1 KiB
Markdown

---
type: decision
tldr: 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.
status: accepted
decided_on: 2026-10-29
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/skills/ckb-lint/scripts/session_start.py, .agents/skills/*/SKILL.md, tests/smoke.sh
confidence: 0.85
quality: 0.8
last_updated: 2026-10-29
freshness_window_days: 365
retention: 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).