home / skills / dmitriiweb / extract-emails / debug-logging-assistant

debug-logging-assistant skill

safe

This skill helps you insert purposeful debug logging to enhance observability without altering behavior in critical modules.

npx playbooks add skill dmitriiweb/extract-emails --skill debug-logging-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.7 KB

---
name: debug-logging-assistant
description: Add 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.

Overview

This skill helps add purposeful debug logging to a Python scraper that extracts emails and LinkedIn links from URLs. It focuses on improving observability without changing program behavior or control flow. The goal is concise, high-signal logs that explain decisions, inputs, and error context for faster troubleshooting.

How this skill works

Inspect the scraper code and recent failures to identify entry points, external requests, parsing branches, and error handlers. Insert debug-level logs before and after risky operations (HTTP calls, HTML parsing, regex extraction) and around branches that affect results. Ensure messages use existing log levels and safe identifiers, and validate there are no functional changes.

When to use it

When failures are intermittent or spikes in missing extractions appear
When adding new data sources or crawling patterns and you need visibility
When debugging parsing edge cases for LinkedIn URL formats or malformed emails
When optimizing retry/backoff behavior or diagnosing rate-limiting
During code review to improve maintainability and future debugging

Best practices

Log concise context: endpoint URL, HTTP status, response size, parsing outcome, and record identifiers (but not raw PII).
Place logs at high-signal spots: request start/end, parse entry/exit, branch decisions, and exception handlers.
Use consistent prefixes and levels already present in the codebase (e.g., scraper.debug, extractor.debug).
Avoid logging full payloads or credentials; redact or summarize sensitive fields (hash counts, domain only).
Keep the volume reasonable: prefer one clear log per logical block rather than many low-value messages.

Example use cases

Record an HTTP request start with target URL and user-agent, then a follow-up with status code and response length.
Log parser branch taken when encountering LinkedIn profile patterns vs search-result patterns, including matched token and outcome count.
On email extraction failure, log snippet length, regex tried, and sample surrounding text (redacted) to reproduce issues.
When retrying after a 429/5xx, log retry count, backoff interval, and whether the eventual request succeeded.

FAQ

Will adding logs change scraper behavior?

No. Logs should only be added without modifying control flow, data transformations, or timing-critical logic. Validate by running tests or smoke checks.

What must I avoid logging?

Never log full personal data (email addresses, profile contents) or credentials. Log safe identifiers, counts, domains, or hashed values instead.