--- 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).