log-structured

/log-structured

What it does

Helps retrofit a codebase to the structured-logging spec from AGENTS.md:

{"ts":"2026-05-24T12:34:56.789Z","level":"info","trace_id":"a1b2c3","span_id":"4d5e6f","service":"billing","event":"invoice_paid","attrs":{"invoice_id":"inv_789"}}

Walks a target path, finds anti-patterns, and emits a structured report with file:line citations and concrete suggested replacements. Never modifies code — the user decides per-finding.

Anti-patterns flagged

| Pattern | Why it's a problem | Suggested fix | |---------|-------------------|---------------| | print(...) in production code | No level, no context, no structure | Replace with logger call | | console.log(...) in production code | Same; not structured | Replace with structured logger | | logger.X(f"user {id} did {action}") (Python) | Values baked into message → agent can't grep event=did_action | Move values to attrs={"user_id": id, "action": action} | | ` logger.x(user ${id} did ${action}) (TS/JS) | Same | logger.info("user_action", { user_id: id, action }) | | fmt.Printf("user %d ...", id) followed by log.Print | Same | slog.Info("user_action", "user_id", id) | | Missing trace_id propagation | Can't reconstruct request flow | Wire context-aware logger (template per lang) | | Logging to stdout in a service that should log structured (e.g., print` in Flask handler) | Operator tooling can't parse | Wire JSON formatter |

Workflow

1. Resolve target. Default . (whole repo). If $ARGUMENTS has a

path, use that. If --lang <name> is given, restrict scan to that language; else auto-detect from file extensions.

1. Detect language(s) by file extension. Walk only files matching:
2. Python: *.py (skip tests/, *_test.py, __pycache__)
3. TypeScript/JavaScript: .ts, .tsx, .js, .jsx (skip

node_modules/, dist/, build/, .test., .spec.)

• Go: *.go (skip *_test.go, vendor/)
• Rust: *.rs (skip target/, tests/)

1. Grep for anti-patterns in the scoped files. Use Grep tool with

the patterns documented per-language in [../../templates/logging/](../../templates/logging/).

1. For each finding, emit:
2. file:line — current line — suggested replacement
3. Reference the language template by path:

see templates/logging/<lang>.md for the logger init

1. Summary at the end:
2. Count by language
3. Count by anti-pattern type
4. Path to the language template for setup
5. Reminder: this skill does NOT modify code

Output format

# Structured logging audit — <YYYY-MM-DD>, <root>

## Findings

### src/billing/charge.py
- **line 47**: `print(f"charged user {user_id}")` →
  `logger.info("user_charged", attrs={"user_id": user_id})`
  See `templates/logging/python.md` for logger setup.
- **line 89**: `logger.error(f"failed: {e}")` →
  `logger.error("charge_failed", attrs={"error": str(e), "trace_id": current_trace_id()})`

### src/api/handler.ts
- **line 23**: `console.log(`req from ${req.ip}`)` →
  `logger.info("request_received", { ip: req.ip, route: req.path })`
  See `templates/logging/typescript.md`.

## Summary

- 2 files scanned
- 3 findings (2 print/console.log, 1 message-interpolation)
- Language templates: see `templates/logging/{python,typescript}.md`
- This audit is read-only. Apply fixes incrementally — start with the
  highest-traffic event types where structured logs pay off fastest.

## Out of scope

- Already-structured logs that just use the wrong field name conventions
  (e.g., `userId` vs `user_id`) — that's a separate harmonization pass.
- Logger choice / library swap — this audit assumes you'll wire a
  structured logger per the template; it doesn't force a specific library.

Hard rules

• Read-only. No Edit/Write in the tool list. If asked to "just fix

the prints" — refuse. The user picks which findings matter; some scripts have print legitimately (CLI output).

• Never assume the logger import. Each finding references the

language template, which documents the logger initialization. Don't hallucinate from app.logger import logger if the project doesn't have one.

• Skip tests by default. Test files often print intentionally for

debugging. If user passes --include-tests, then scan them too.

• One finding per line. Don't bundle multiple patterns on the same

line into one finding — file:line citation must be precise.

Tunables

• --lang <name> — restrict scan to one language.
• --include-tests — scan test files too.
• --max-findings <N> — cap output (default 100; large repos can

produce thousands of findings, most are noise after the first 50).

When to run

• Onboarding into a legacy codebase that pre-dates the convention.
• After AGENTS.md adoption — run once to see baseline.
• Before a structured-logging migration to size the work.
• After major refactoring of logging code, to catch regressions.

Pairs naturally with /init-repo (which can drop the language template into a new project) and with the AIDEV-NOTE convention (anchor the non-obvious logging decisions in code).