debug_skill

Overview

This skill documents how to use the debug package for consistent, namespaced logging across the codebase. It explains namespace conventions, format specifiers, and how to enable debug output in browser, Node, and Electron environments. Use it to add targeted debug statements without cluttering production logs.

How this skill works

It shows how to create a logger with debug('lobe-[component]:[module]') and then call log(...) with format specifiers for structured output. The guide defines standard namespaces for desktop, server, client, and routers so log output can be filtered by area. It also covers enabling debug output via localStorage, environment variables, or process.env depending on runtime.

When to use it

• Adding debug logging during feature development or troubleshooting
• Instrumenting request handlers, routers, and background tasks
• Inspecting complex objects or function inputs/outputs
• Filtering logs by subsystem during local dev or CI debugging
• Implementing per-module debug flags in Electron apps

Best practices

• Use the lobe-[component]:[module] convention to keep namespaces consistent
• Prefer %O for complex objects to get expanded, inspectable output
• Keep debug calls lightweight; avoid heavy synchronous work inside log statements
• Enable debug only in development or targeted runs (DEBUG or localStorage) to avoid noise
• Document new namespaces when adding modules so team members can enable them easily

Example use cases

• Server router: const log = debug('lobe-server:market'); log('getAgent input: %O', input)
• Desktop component: debug('lobe-desktop:auth') to trace auth flows and UI triggers
• Client feature flagging: debug('lobe-client:featureX') to confirm client-side behavior
• Edge router development in Electron: process.env.DEBUG = 'lobe-*' for full trace during manual testing
• Ad-hoc local debugging: localStorage.debug = 'lobe-server:market' to focus only on market logs