Logging

Exclusions

Never analyze files in these directories:

• Build artifacts: bin/, obj/, build/, dist/, target/, out/, __pycache__/
• Dependencies: node_modules/, vendor/, .venv/, packages/, Packages/
• Generated code: directories or files with auto-generated headers (// <auto-generated>, # Generated by, etc.)
• Version control: .git/, .svn/, .hg/

Never analyze these file types:

• Pure data models / DTOs / POCOs / records with only properties and no logic
• Interface / trait / protocol definitions (no implementation)
• Enum / constant definition files
• Test files (they contain test-specific logging, not production logging)
• Configuration files (JSON, YAML, XML, TOML, INI, .env)
• Migration / SQL files
• Documentation files (Markdown, reStructuredText, etc.)

If the user explicitly requests an excluded file or directory, explain why it is excluded and ask for confirmation before proceeding.

Phase 0: Detection

0.1 Detect Programming Language

Identify the programming language(s) in scope by examining:

• File extensions (.cs, .java, .py, .ts, .js, .go, .rs, .rb, .php, etc.)
• Build/project files (*.csproj, *.sln, pom.xml, build.gradle, package.json, go.mod, Cargo.toml, Gemfile, composer.json, etc.)

0.2 Identify Existing Logging Framework

Search the codebase for imports, usings, and instantiation patterns to detect the logging framework:

If NO logging framework is found: Report to the user: "No existing logging framework detected in the project. This skill works with existing logging infrastructure and does not introduce new frameworks. Please set up a logging framework first, then re-run this skill." Stop here.

If MULTIPLE frameworks are found: Report all detected frameworks with file counts for each. Identify the dominant framework (most usage). Ask the user which framework to standardize on, or proceed with the dominant one.

0.3 Document Existing Conventions

Analyze 5-10 representative files with existing logging to document:

1. Logger instantiation pattern: How is the logger created or injected?

   • Constructor injection: public MyService(ILogger<MyService> logger)
   • Factory method: private static readonly ILogger Logger = LoggerFactory.Create(...)
   • Static logger: private static readonly Logger _log = LogManager.GetCurrentClassLogger()
   • Module-level: logger = logging.getLogger(__name__)

2. Logger field/variable name: _logger, logger, log, _log, LOG, LOGGER

3. Message format:

   • Structured templates: _logger.LogDebug("Processing {Filename}", filename)
   • Format strings: logger.debug("Processing %s", filename)
   • f-strings / interpolation: logger.debug(f"Processing {filename}")
   • Concatenation: logger.debug("Processing " + filename)

4. Parameter naming convention: PascalCase, camelCase, snake_case, UPPER_CASE

5. Sensitive data handling: Does the project use masking utilities, redaction functions, or no special treatment?

6. Context enrichment: Correlation IDs, request context, scoped properties, MDC

7. EventId / marker usage: Does the project use categorized event IDs or markers?

Present a brief summary of detected conventions:

Detected Logging Setup:
- Language: C# (.NET)
- Framework: ILogger<T> with Serilog
- Logger field: _logger (constructor-injected)
- Message format: Structured templates with PascalCase parameters
- Sensitive data: SensitiveDataMasker.Mask() utility
- Context: MigrationContext appended via {MigrationContext} placeholder
- EventIds: MigrationEvent.* constants used in infrastructure layer

Phase 1: Analysis

Read every source file in scope (respecting Exclusions above). For each file, evaluate the following categories.

1.1 Missing Logging Statements

Identify methods, code paths, and locations that SHOULD have logging but currently do NOT. Apply the criteria from the "Criteria for New Logging Statements" section below.

For each finding, record:

• File and line number (or method name)
• What is missing (e.g., "method entry logging", "exception not logged in catch block")
• Recommended log level (per Decision Tree)
• Draft log message in the detected convention style, using --lang language

1.2 Incorrect Log Levels

Check every existing log statement against the Log-Level Decision Tree (below). Flag any that use the wrong level.

For each finding, record:

• File, line number, current log statement
• Current level and recommended level
• Reason for the change

1.3 Duplicate Logging

Identify cases where the same information is logged multiple times:

• Same or very similar message logged in both caller and callee method
• Exception logged at catch site AND re-thrown to be logged again by the caller
• Redundant "entering method" followed by identical "method called with params" log
• Same event logged at multiple levels without additional context at each level

For each finding, record:

• Both locations (file + line)
• Which one to keep (prefer the layer that owns the operation)
• Which one to remove

1.4 Pattern Violations

Check existing logging for violations of the project's detected conventions:

• String interpolation/concatenation instead of structured templates (if framework supports structured logging)
• Missing logger instantiation in classes that have business logic but no logger
• Sensitive data logged without masking — connection strings, tokens, passwords, API keys, or secrets logged in plain text
• Inconsistent logger naming — logger field names that differ from the project convention
• Inconsistent instantiation — mixing DI and static creation in the same project layer

1.5 Report

Present findings as a structured report:

## Logging Analysis Report

### Detected Setup
- Language: [detected]
- Framework: [detected]
- Conventions: [summary from Phase 0.3]
- Log message language for new statements: [--lang value]

### Summary
| Category              | Count |
|-----------------------|-------|
| Missing logging       | N     |
| Incorrect log levels  | N     |
| Duplicate logging     | N     |
| Pattern violations    | N     |
| **Total issues**      | **N** |

### By File/Directory
| Location | Missing | Wrong Level | Duplicates | Violations |
|----------|---------|-------------|------------|------------|
| ...      | ...     | ...         | ...        | ...        |

### Detailed Findings

#### Missing Logging
[For each: file:line, what is missing, recommended level, draft message]

#### Incorrect Log Levels
[For each: file:line, current statement, current level -> recommended level, reason]

#### Duplicate Logging
[For each: both locations, which to keep, which to remove]

#### Pattern Violations
[For each: file:line, violation type, current code, recommended fix]

If --analyze-only was specified, stop here.

Phase 2: Checkpoint

Present the analysis summary and ask:

Logging analysis complete. [X] issues found across [Y] files.

Breakdown:
- [N] missing logging statements to add
- [N] incorrect log levels to correct
- [N] duplicates to remove
- [N] pattern violations to fix

Options:
1. Apply all changes
2. Apply to specific file/directory only — tell me which
3. Cancel — make no changes

Wait for user response before proceeding.

Phase 3: Apply Changes

Apply changes file by file, grouped by category:

3.1 Add Missing Logging

• Create new logging statements using:

  • The detected logger instantiation pattern
  • The detected message format convention
  • The detected parameter naming convention
  • The --lang language for message text
  • Appropriate log level per the Decision Tree
  • Sensitive data masking if the project uses it
  • Context enrichment if the project uses it
  • EventIds/markers if the project uses them AND an appropriate existing one matches

• If a class needs a logger but has none:

  • Add the logger field/variable following the project's instantiation pattern
  • Add necessary imports/usings
  • Add constructor parameter if using dependency injection

3.2 Fix Incorrect Levels

• Change only the log level method/enum; preserve the message template, parameters, and all other code

3.3 Remove Duplicates

• Remove the redundant log statement
• Keep the statement at the most appropriate location (the layer that owns the operation)
• If the kept statement needs additional context that was only in the removed one, merge the context

3.4 Fix Pattern Violations

• Convert string interpolation/concatenation to structured templates (preserve semantics)
• Add missing logger instantiation following project conventions
• Wrap sensitive data with the project's masking utility
• Normalize logger naming to match project convention

If --fix-levels-only was specified, only apply step 3.2.

3.5 Build Verification

After all files are modified, run the appropriate build/compile command:

If the build fails:

1. Read the error output
2. Fix compilation errors (missing imports, parameter mismatches, type errors, etc.)
3. Re-build

Maximum 3 iterations. If build still fails after 3 attempts, stop and report remaining errors to the user.

Phase 4: Summary

Present a final summary:

## Logging Changes Applied

### Statistics
| Category              | Count |
|-----------------------|-------|
| Statements added      | N     |
| Log levels corrected  | N     |
| Duplicates removed    | N     |
| Violations fixed      | N     |
| **Total changes**     | **N** |

### Files Modified
[List each file with change counts]

### New Logger Instantiations
[List any classes/modules that received a new logger, with the instantiation pattern used]

### Build Verification
- Result: [Success / Failed with N remaining errors]
- [If failed: list remaining errors]

Log-Level Decision Tree

Apply these rules in order. Use the first matching rule.

CRITICAL / FATAL

Use when ALL of these are true:

• The application CANNOT continue operating
• The error affects the entire system, not just one operation
• No recovery or fallback is possible

Examples: database completely unreachable after all retries, critical infrastructure creation failed, application host cannot start, unrecoverable corruption detected

ERROR

Use when ALL of these are true:

• An operation FAILED and could not complete its intended task
• Data may be lost or inconsistent
• But the application can continue processing other operations

Examples: database update failed, file processing aborted with error, API call failed after all retries, hash validation found corruption, migration execution threw exception

WARNING

Use when ANY of these are true:

• Something unexpected happened but the operation can continue or recover
• A fallback or retry was used successfully
• Configuration is suboptimal or deprecated
• A resource was not found but this is handled gracefully
• An operation was skipped for a valid reason

Examples: file not found but handled, retry succeeded after transient failure, deprecated config option used, operation skipped due to filter, rollback file missing during validation

INFORMATION

Use when ALL of these are true:

• The event documents normal, expected application flow
• A business-level operation started, progressed, or completed
• The message would be useful in a production log for operational monitoring

Examples: "Service started", "Migration completed: {Count} files applied", "Import finished: {RecordCount} records processed", "Configuration loaded for environment {Environment}"

DEBUG

Use when ALL of these are true:

• The message helps developers understand what the code is doing
• It includes specific parameters, method names, or state values
• It would be too verbose for production but essential for troubleshooting

Examples: method entry with parameters, configuration values loaded, state transition details, decision branch taken, DAL properties initialized, template execution results

TRACE / VERBOSE

Use when ANY of these are true:

• The message dumps complete contents (full SQL blocks, file contents, config sections, request/response bodies)
• Every iteration of a loop is logged individually
• Internal algorithmic decisions are recorded step by step
• The volume would be overwhelming in any environment except deep debugging

Examples: "SQL block {Block}/{Total}:\n{SqlContent}", "File content:\n{Content}", complete configuration dumps, per-iteration processing details

Key Distinctions

Criteria for New Logging Statements

The skill actively identifies where logging is missing and adds appropriate statements. Use these criteria to decide what new logging to add:

Anti-Patterns: Do NOT Add Logging For

• Trivial getters, setters, or property accessors
• Pure mathematical or string utility functions
• Every single line of code (logging is not line-by-line tracing)
• Constructor bodies that only assign fields (the DI container logs resolution)
• Empty methods or methods that only delegate to another method
• Code that is already adequately logged by the caller or callee (avoid duplication)

Convention Compliance Checklist

Before writing any new log statement, verify it follows ALL detected conventions:

• Uses the project's logger instantiation pattern
• Uses the correct logger field/variable name
• Uses the project's message format (structured templates, format strings, etc.)
• Uses the project's parameter naming convention
• Wraps sensitive data with the project's masking utility (if applicable)
• Includes context enrichment (if the project uses it)
• Uses an existing EventId/marker (if the project uses them and one matches)
• Log message text is in the language specified by --lang
• Does not duplicate information already logged nearby