do-informative-logging

Mimir metadata (required on apply): always_apply: true (currently false). This rule absorbs and replaces add-logging.

Every service call or controller action must log to logs/app.log (or the project’s designated app log) at INFO. Configure logging if missing: logger + file handler that rotates / clears on every app relaunch so diagnosis starts clean.

Use logs/app.log to troubleshoot who was doing what with which data when error X occurred. For UI / HTMX flows use console.log for decisions, actions, and results (map to the same story beats below).

Ban deferred-logging slices. Logging ships in the same green slice as behavior — never a final “informative logging pass” after tests are green.

Ask yourself before writing each log line:

• What information will I need to precisely pinpoint where the error is occurring?
• What context will I need in the logs to understand why it happened?
• What data transformations or validations occurred?
• Which decisions led to the current point?

Story beats (minimum narrative)

On each major step emit the applicable beats so a reader can reconstruct the path:

entry → config → validation → processing → branch → exit → error

Preferred line format (grep / caplog friendly)

{logger_name} | {Class.method} | {beat} | key=value ...

Legacy Class.method: message | key=value is acceptable if where + beat intent remain searchable.

Logging setup

import logging
import io
from pprint import pformat
from tabulate import tabulate

logger = logging.getLogger(__name__)
buffer = io.StringIO()  # structured dumps

Buffers: use StringIO; log buffer.getvalue(), then truncate(0) (and seek(0) if reusing). Summaries: include shape/types, head/tail/describe, null counts where useful.

Patterns (examples)

1. Entry

def method_name(self, param1, param2):
    logger.info(
        f'{self.__class__.__name__}.method_name | entry | param1={param1} param2_shape={getattr(param2, "shape", type(param2))}'
    )