debug-with-file_skill

Overview

This skill implements an interactive, hypothesis-driven debugging workflow that records exploration, tracks evolving understanding, and uses analysis-assisted evidence to guide fixes. It creates a reproducible session with NDJSON logging, iterates on testable hypotheses, and documents corrections and lessons learned. The process emphasizes consolidation of verified knowledge and retention of learning from failed attempts.

How this skill works

On first run it scans the codebase for likely error locations, creates an understanding document, and generates 3–5 testable hypotheses with instrumentation points. The user runs reproduction steps to produce an NDJSON debug log. In analyze mode the skill parses the log, groups entries by hypothesis, evaluates evidence against criteria, updates the understanding document with corrections, and either recommends a fix or proposes next experiments. Once a hypothesis is confirmed, it guides fix application, verification, and cleanup of instrumentation.

When to use it

• Investigating intermittent or hard-to-reproduce bugs where evidence collection matters
• When you want a documented timeline of exploration and decisions
• During team debugging to preserve reasoning and hand off context
• When multiple hypotheses are plausible and need evidence-based validation
• To retain learning from failed experiments for future troubleshooting

Best practices

• Write concise reproduction steps and run them before analysis
• Instrument minimal relevant state to keep logs readable and privacy-safe
• Define clear confirm/reject criteria for each hypothesis
• Iterate quickly: reject/inconclusive leads to focused next experiments
• Consolidate disproven assumptions into a single "What Was Disproven" section

Example use cases

• A backend API intermittently returns empty payloads: generate hypotheses about upstream data, timing, or parsing errors and log key values.
• A race condition surfaces under load: add timestamped NDJSON entries to confirm ordering and latencies.
• A type/format parsing failure: instrument parsed values and schema checks to confirm mismatched expectations.
• A third-party integration times out: log request/response metadata and network timing to confirm integration vs local issue.