debug-protocol

Debug Protocol — Evidence-First Reproduction

A systematic approach to debugging when the expected instrumentation (logs, telemetry, debug servers) fails or is unavailable. This protocol prioritizes using directly observable evidence early and pivoting quickly when a collection strategy stalls.

Core Principles

1. Available evidence is ground truth from round one. Do not delay with parallel collection mechanisms (e.g., trying to set up a debug server, waiting for telemetry) when you already have direct evidence (screenshots, console output, error messages, stack traces). The direct evidence has higher signal-to-noise than speculative instrumentation.

2. Pivot after two failed collection rounds. If a logging mechanism, telemetry pipeline, or debug-server strategy fails to produce output twice in a row, stop and switch to an alternative evidence source immediately. Do not attempt the same collection mechanism a third time. The cost of a third failed round (time spent, additional system state changes) outweighs the benefit of "one more attempt."

3. Each reproduction round is a scarce resource. Running the system again to trigger the bug consumes real time and may change system state. Minimize reproduction rounds by extracting maximum information per run. Plan observation points before each round; don't go in blind hoping to see something useful.

4. Name the failure mode. When a collection strategy fails, don't use vague language ("the logs aren't working"). Name the specific failure: "telemetry batching delay blocking runtime output," "log file permissions preventing write," "debug server timeout on initialization." Naming makes clear what the next alternative should address.

Reproduction Workflow

Round 1: Establish baseline with available evidence

• Identify what you can observe directly without new instrumentation: stdout/stderr, console logs already in memory, screenshots, error dialog text, HTTP response bodies, database query results, file system state, process list, network traffic already captured.
• Extract all ground-truth information from these sources. Document the failure mode and expected vs. actual state in detail.
• If the error is reproducible and you have good signal-to-noise evidence, consider whether additional instrumentation is even necessary before proceeding to round 2.