63 lines
3.1 KiB
Markdown
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).
|