debug-logging-assistant

dmitriiweb's avatarfrom dmitriiweb

Add purposeful debug logging to improve observability without changing behavior.

⭐106stars🔀38forks📁View on GitHub🕐Updated Jan 2, 2026
[Debugging]

When & Why to Use This Skill

The Debug Logging Assistant is a specialized Claude skill designed to enhance software observability by strategically inserting purposeful debug logs into existing codebases. It helps developers identify critical execution paths, monitor external API calls, and capture error contexts without altering the application's functional logic, making it an essential tool for efficient troubleshooting, system maintenance, and performance monitoring.

Use Cases

  • Troubleshooting Production Failures: Identifying areas with low visibility following system errors and adding logs to capture inputs and state at the moment of failure.
  • Monitoring Complex Logic: Inserting logs into intricate branching paths and decision points to track execution flow and data transformations in real-time.
  • External Integration Auditing: Adding logs around external API calls, database queries, and third-party services to monitor latency, success rates, and response integrity.
  • Legacy Code Onboarding: Enhancing the observability of older, undocumented codebases by adding trace logs to map out execution patterns without risking functional regressions.
namedebug-logging-assistant
descriptionAdd purposeful debug logging to improve observability without changing behavior.

Debug Logging Assistant

Quick start

  • Read the target code and recent failures to understand where visibility is missing.
  • Add debug logs only where they help explain flow, inputs, branching, or error context.
  • Keep logs small and descriptive: what is happening, key identifiers, and outcomes.
  • Do not change control flow or data; only add logs. Avoid logging every step.
  • See references/logging_rules.md for placement and messaging guidelines.

Workflow

  1. Inspect

    • Identify high-signal spots: entry points, external calls, branching paths, retries, and error handling.
    • Note important identifiers (IDs, counts, feature flags) that disambiguate paths.

  2. Place logs

    • Log before/after risky operations and around decisions that affect downstream behavior.
    • Prefer one concise log per logical block over multiple low-value messages.
    • Keep sensitive data out; include only safe identifiers or summaries.

  3. Write messages

    • Use consistent prefixes and log levels (debug/trace) already used in the codebase.
    • Capture intent: action, inputs of interest, and outcomes (success/failure, counts).
    • Avoid narrating trivial steps or restating obvious code.

  4. Validate

    • Ensure no functional changes: no refactors, no reordered logic, no added branching.
    • Confirm log volume is reasonable and won’t spam hot paths.
    • Re-run applicable tests if available; otherwise double-check for typos.

Reference

  • references/logging_rules.md: detailed rules for meaningful debug logging.