Logging Cleanup Skill

# Logging Cleanup Skill

---
slug: logging-cleanup-skill
version: 1.0.0
category: engineering
command: /clean-logs
---

## What it does
Audits logging calls in a file or module and rewrites them to be production-ready:
removes debug noise, converts ad-hoc `console.log` / `print` calls to structured
logger calls with correct levels, adds contextual fields (request ID, user ID, etc.),
and flags any PII or secrets being logged. Works with any structured logger
(pino, winston, structlog, zap, slog) — infer from imports, or ask.

## Trigger
Use this skill when asked to clean up, normalize, or audit logging.
Typical invocations:
- "Clean up the logging in this file — it's full of console.logs"
- "Make our logging structured and production-safe"
- `/clean-logs` in Claude Code
- `/clean-logs <file>` to target a specific file or module

## Input
Provide one or more of:
1. The file or module to audit (pasted code or file path)
2. The structured logger in use (pino, winston, structlog, zap, slog — will be inferred if not stated)
3. Fields that should appear on every log line (e.g. `requestId`, `userId`, `service`)
4. The environment context (production / development affects which levels are safe to emit)

## Method

Run four passes:

### Pass 1 — Remove debug noise
Identify and remove (or downgrade) logging that has no place in production:
- `console.log('here')`, `console.log(someObject)` left from debugging
- Logging inside tight loops (N log lines per request)
- Logging entire request or response bodies at INFO or above (should be DEBUG / TRACE only)

### Pass 2 — Promote to structured logger
Replace bare `console.log` / `print` / `fmt.Println` with the project's structured logger.
Convert string interpolation into structured fields:
- Before: `console.log(`User ${userId} signed in`)`
- After: `logger.info('user signed in', { userId })`

### Pass 3 — Enforce correct log levels

| Level | When to use |
|-------|-------------|
| `error` | Unexpected failures that require attention; always include the error object. |
| `warn` | Recoverable anomalies: retries, fallbacks, deprecated API usage. |
| `info` | Significant lifecycle events: server start, job complete, user action. |
| `debug` | Diagnostic detail useful when investigating a specific issue; not emitted in production by default. |
| `trace` | Highly verbose: per-request details, loop iterations. Only for deep debugging. |

Downgrade INFO to DEBUG when the event is too frequent to be actionable in production.

### Pass 4 — Flag PII and secrets
Scan log arguments for fields that may contain regulated or sensitive data:
- Email addresses, phone numbers, IP addresses (PII in most jurisdictions)
- Passwords, tokens, API keys, credit card numbers
- Full names or any field named `password`, `token`, `secret`, `ssn`, `dob`, `email`

Flag each occurrence with a recommendation to redact or omit the field.

## Output format

Produce the rewritten file, then a **Changes** section:

```
## Changes
1. Removed 4 debug console.log calls (lines 12, 18, 34, 41) — no production value.
2. Promoted 3 string-interpolated console.log calls to logger.info with structured fields.
3. Downgraded request.body log from INFO to DEBUG (line 27) — too verbose for production.
4. [PII] logger.info at line 55 logs user.email — redact or remove this field.
```

## Example output

**Before**
```typescript
console.log('processing payment');
console.log('user:', user);
try {
  const result = await stripe.charge(amount);
  console.log('charge result:', result);
} catch (e) {
  console.error('stripe failed: ' + e.message);
}
```

**After**
```typescript
logger.info('payment processing started', { userId: user.id, amountCents: amount });
try {
  const result = await stripe.charge(amount);
  // log the charge ID, not the full result object — avoids logging card metadata
  logger.info('payment charge succeeded', { userId: user.id, chargeId: result.id });
} catch (e) {
  logger.error('payment charge failed', { userId: user.id, error: e });
}
```

## Changes
1. Removed `console.log('processing payment')` — replaced with a structured INFO that includes userId and amount.
2. Removed `console.log('user:', user)` — logging the full user object at line 2 included user.email (PII). Use `user.id` only.
3. Replaced string-interpolated `console.error` with `logger.error({ error: e })` — passes the error object so stack traces appear in logs.
4. [PII warning] The original code logged `user.email`; the rewrite uses `user.id` only. Confirm this is sufficient for your debugging needs before removing the email field.

## Commands (Claude Code)

- `/clean-logs` — Audit and rewrite logging calls in the selected or pasted code.
- `/clean-logs <file>` — Audit a specific file or module for debug noise, wrong levels, and PII in logs.