logger
Apply the shared logging contract and lifecycle pairing. Use when adding, changing, or reviewing log statements in any driver.
SKILL.md.claude/skills/logger/SKILL.md
GitHubLogging
The normative reference is the shared
SPEC.md: it owns
the eight variants, the importance/lifecycle grid, punctuation, and driver
conformance contract. AGENTS.md owns the universal English and fail-fast
rules. This skill covers how to apply and verify that contract in practice.
Log extensively
Under-logging is the default failure. Every meaningful state change, lifecycle event, decision and failure path gets a line. Future debugging depends on it — including yours, tomorrow, from a user's log file with no repro.
Selection heuristic: "would I need this line to diagnose a bug in production?"
Yes → info or above. Only useful during active development → debug/trace/done.
High-frequency events (per keystroke, per frame) → debug only.
The pairing rule is enforced
start ↔ success and trace ↔ done must always come in pairs. This is not
cosmetic: a START with no matching SUCCESS in a log is the primary signal
of a silent failure, and the whole convention exists to make that visible.
tests/meta/infra/logger/test_logger_pairing.ahk checks this. An unpaired lifecycle call
fails the suite.
Practical consequence: if a function can return early between start and
success, every early-return path needs its own terminal log — usually an
error or warn, not a success.
Common mistakes
- Swallowing an error and logging nothing. Violates the fail-fast contract
in
AGENTS.md. A baretry … catch {}is never acceptable; at minimum log aterror. successon a path that did not succeed. A function that could not fulfil its contract must say so via return value and log.- Setters that do not log. Every public setter logs its new value at
debug, as specified by the shared logger contract; this makes a boot log reconstruct the exact applied config. - French log text. Logs are developer-facing and always English; only UI
strings are French (see the
i18nskill). - A
startwhosesuccesssits after areturn. Reads fine, never fires.
Throttling
High-frequency error paths need a throttle (the hook dispatcher uses a 60 s per-label cache) or a single failing keystroke floods the log and buries the context you need. Throttle the repeat, never the first occurrence.