| name | logging |
| description | Add, fix, or update logging in project code |
| argument-hint | [scope: file|module|all] |
| context | fork |
| agent | log-writer |
Logging Scope
$ARGUMENTS
Add, fix, or update logging following strict principles.
Core Principle: Signal over Noise
Logs that don't get read are useless. Every log statement must earn its place.
Before adding a log, ask:
- Will someone look at this?
- Does this help diagnose something?
- Is this the right level?
- Is there already a log covering this?
Cut ruthlessly. Then cut more.
Log Levels
1. INFO: The Service Narrative
What the service is doing at a glance.
Log these:
- Service startup/shutdown
- External connections established/closed (WebSocket, DB)
- Subscriptions to new resources
- Periodic heartbeats (every N seconds: "processing X markets")
- HTTP requests going out (target, method)
- Key state transitions
Never log:
- Every function entry/exit
- Internal data transformations
- Things that happen thousands of times per second
2. DEBUG: Granular Internals
Details for troubleshooting. Off in production unless investigating.
Log these:
- Request/response payloads (redact secrets)
- Internal state changes
- Timing breakdowns
- Configuration values at startup
- Loop iterations when relevant
3. WARN: Rare by Design
Recoverable errors you're explicitly allowing to continue.
Log these:
- Fallback to default config
- Retryable failures that succeeded on retry
- Resource thresholds approached (memory at 80%)
- Deprecated API usage detected
Never log:
- Expected conditions (user not found, validation failed)
- Anything you'd ignore in production
4. ERROR: Every Failure
Log at the handling point. Once.
- Use language/framework hooks to catch all errors automatically
- Include context: what was being attempted, relevant IDs
- Don't log and rethrow—pick one
- Stack traces for unexpected errors
Process
- Identify scope (file, module, or all)
- Audit existing logging against these levels
- Add missing INFO logs for external-facing events
- Remove noisy/redundant logs
- Ensure ERRORs are logged at handling points
- Use framework-provided logging (HTTP interceptors, etc.) where available
- Remind: run
/logging after significant code changes
No Scope Specified?
Review ALL logging against current code. Fix level mismatches. Remove noise. Add missing service narrative. Report what was changed.
