3.1 KiB
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
ckb-lint/scripts/session_start.pyperforms Rule E's start in one call: identity, title (stored unless already set),announce_title, git status,lint_report.py --quick,autosave_hook.py --checkonly when the switch or a hook file exists,routines.py --due, and the last##block of the latestworkload/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.- Rule E in
AGENTS.mdnames the command and the action per output line. The no-Python fallback stays as before (lint_quick.sh/.ps1plus the git and workload steps by hand, routine check skipped). wiki/index.mdis 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.- A skill's
## Purposeholds 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. - Rule B's log-entry format lives in
AGENTS.mdonly; 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;
## Purpose16.2k → 7.8k across the skills, up to 1.9k saved per trigger forckb-index-externalandckb-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 ofckb-upgrade/ckb-init(splitting rarely-run steps into references adds a read exactly when they run).