logging

name	logging
description	Use this skill when adding logging to production code or asserting on log output in tests. Covers structured logging, level discipline (info/warn/error/debug), event-keyword conventions (:domain/action), and feature-test assertions on log entries.

Logging Discipline

When This Skill Applies

Use this skill whenever you are adding log calls to production code, deciding what level a log entry deserves, or writing tests that assert on log output.

Structured maps, not strings

Log entries must be structured maps, never raw strings. A structured map is filterable, searchable, and assertable. A raw string is none of those.

;; GOOD — structured
(log/info {:event :session/created :session-id id :provider :anthropic})

;; BAD — raw string
(log/info (str "Session created: " id))

Include contextual identifiers — session, user, route, tool, provider — when available. Future-you will thank present-you when grepping logs at 2am.

Levels

Only info and above are spec-worthy in feature assertions. Debug is for internal tracing; tests should not assert on debug output.

Level	Use for
info	Lifecycle events: created, opened, started, completed
warn	Degraded-but-continuing states (override, retry, fallback)
error	Failure paths visible to the operator
debug	Internal tracing — not asserted in tests

Rules for new code

• Emit info for session lifecycle, request lifecycle, server lifecycle, long-running operations.
• Emit error for all failure paths visible to the operator.
• Emit warn for degraded-but-continuing states (e.g. config override accepted, slow path engaged).
• Emit debug for internal tracing; do not add feature assertions for debug events.
• Network, tool, and boundary code must log failures as structured maps.
• Every new info+ log call needs a feature scenario asserting it.

Event keyword convention

Event names follow :domain/action — keyword namespace identifies the subsystem, name identifies what happened. Keep them grep-friendly.

:session/created
:session/compaction-started
:tool/exec
:tool/execute-failed
:auth/login
:server/started
:config/set
:config/schema-registered

This is the single most important logging convention. It makes events discoverable (grep ':session/'), filterable in log pipelines, and unambiguous when multiple subsystems emit similar-sounding events.

Feature assertion pattern

Then the log has entries matching:
  | level  | event                 | sessionId |
  | :info  | :session/created      | my-chat   |
  | :info  | :session/opened       | my-chat   |

Columns are a subset of the structured log fields; omit fields you don't care about.

Every scenario that performs a mutation or notable lifecycle event should assert its log entry. Missing log assertions let logging silently die — a regression where a mutation stops emitting info-level events goes unnoticed until someone is debugging in production.