# Logging Style Guide

This document defines a consistent logging style for all bot modules, covering levels `silly`, `debug`, `info`, `warn`, and `error`.

## 1. Message Structure
• Prepend a **component tag** in square brackets (e.g. `[init]`, `[cmd:exit]`, `[module:responsesPrompt]`, `[PB]`).
• Follow with a concise verb phrase. Capitalize the first letter. No trailing period.
• Embed variable IDs or names in backticks.

**Example:**
```
[cmd:status] Generated status for client `IO3`
[PB] Missing record for clientId=`ASOP`, creating new one
[module:responses] Fetched 24 messages from channel `123456789012345678` in 120ms
```

## 2. Level Guidelines
- **error**: Unrecoverable failures. Include operation, relevant IDs, and `err.message`.
- **warn**: Recoverable issues or unexpected states (fallbacks, missing optional config).
- **info**: High-level lifecycle events and successful actions (login, module load, command registration).
- **debug**: Detailed internal state and computation values for troubleshooting.
- **silly**: Very verbose, lowest priority; use sparingly for deep diagnostics.

## 3. Where to Log
- In every `catch` block: use `logger.error` with context and message. Optional stack at debug.
- On module initialization: `logger.info` “Module X loaded”.
- When registering slash commands: `logger.info` for each command.
- Before/after major API calls (PocketBase, OpenAI): `logger.debug` with parameters and durations.
- On unexpected user input or missing resources: `logger.warn`.
- On successful command execution: optional `logger.info`.
- In background jobs (cron, cycles): `logger.info` at start/stop, `logger.error` on failure.

## 4. Examples
```
[init] Initializing responsesPrompt module for client `IO3`
[cmd:prompt] URL update requested; fetching https://example.com/prompt.txt
[PB] Upsert `responses_prompts` record id=`abc123` for clientId=`IO3`
[onMessage] Should respond? mention=false reply=true
[sendNarrative] Calling AI with model `gpt-4o-mini`, instructions length=512
Error: [sendNarrative] HTTP 502 Bad Gateway
[cron] Scheduled score decay: `0 0 * * 0`
```

## 5. Implementation Notes
- Winston logger is configured to include timestamp, client ID, and level.
- Always use `logger.<level>(message)` instead of `console.log`.
- Reserve `info` for user-facing or operational milestones.
- Use `debug`/`silly` for verbose, development-only details.
- Update or remove non-conforming logs during code refactoring.