automated-instrumented-debugging_skill

Overview

This skill provides a systematic debugging capability that automates evidence collection via lightweight dynamic instrumentation. It injects small probes into JavaScript code to stream execution events to a local debug server, enabling precise reconstruction of execution flow. Use it when manual tracing is tedious or when code runs in restricted or blind environments.

How this skill works

You run a local debug server and add short probe blocks (wrapped with #region DEBUG) that call a local HTTP endpoint with structured events: function entry, variable snapshots, exits, and errors. During reproduction runs the probes POST JSON logs to the server, which you can query by session to analyze chronology, data values, and the last successful step. After fixing the issue you remove probe blocks with an automated cleanup script.

When to use it

• Bugs that span multiple functions or asynchronous chains (3+ hops).
• Code executing in blind environments: Docker, CI, remote hosts, or headless systems.
• When you need an ordered chronology of events after execution completes.
• When ad-hoc console logs are insufficient or too scattered to prove causality.
• When you want reproducible, auditible evidence to validate a hypothesis.

Best practices

• Define a hypothesis and decide which variables and entry/exit points to capture before instrumenting.
• Wrap all probes in a consistent #region DEBUG so they can be removed automatically.
• Use non-blocking probes (fetch with .catch) and place them after variable definitions to avoid altering behavior.
• Record session IDs to correlate logs from multiple processes or runs.
• Always run the cleanup script after verification to avoid committing probes to the codebase.

Example use cases

• Tracing a race condition across async callbacks by logging function entries and exits with timestamps.
• Investigating a flaky CI failure where interactive debugging is not possible; collect logs remotely and analyze chronology.
• Capturing variable snapshots before and after transformations to identify unexpected mutations.
• Identifying the exact function that throws in a deep call chain by logging error events with stack traces.
• Proving or disproving a data-flow hypothesis when code paths are conditional and infrequently exercised.