01
What this skill does
Use this skill when code reading is not enough and a runtime bug should be followed from failure contract to verified repair. It builds a code-grounded causal map, records material hypotheses with both confirming and rejecting evidence, and validates one coverage-plan file containing a strict attached/unavailable/unsafe debugger strategy, an explicit initial/deferred breakpoint batch, structured probes, and a terminal or observation-checkpoint completion mode. When a native debugger is attached and pausing is safe, the agent installs every safe nonredundant initial breakpoint in one pre-execution phase instead of advancing through a token one- or two-breakpoint set; when suspension is unsafe or unavailable, it retains every candidate as an explicitly reasoned deferred breakpoint and uses validated non-pausing probes. The plan is reused for collector location sync and expected-probe analysis. Each active probe uses a fixed all-occurrences/every-execution contract: every accepted occurrence becomes exactly one independently serialized event and one persisted NDJSON record; a multi-event envelope changes framing only. Each runtime run uses a user handoff by default. A pre-run assignment of runtime investigation may select an autonomous agent chain, but asking the agent to investigate after a completed user run resumes evidence analysis without relabeling that run or transferring future reproduction ownership; a future run changes owner only through explicit run-scoped delegation. Lifecycle scope is investigation over collector session over run: user replies, evidence analysis, context compaction, repair, and new run IDs resume the exact active ready file from the same investigation ledger. A healthy resumed collector keeps its endpoint, port, evidence file, existing dashboard, IDE selection, and location state without another start or UI open; resume never scans the workspace or opens browser UI. Newly established browser-capable local sessions automatically attempt to open and confirm the dashboard with bounded fallback attempts, while the live views, filtering, detail inspection, IDE source opening, location sync, and configuration interactions remain available. Event delivery is language-neutral: reuse an authoritative project or host logger first, otherwise use the target runtime's native HTTP client, with collector-free direct NDJSON append only under safe writer ownership. The skill ships no target-project transport module. The collector exposes only `POST /ingest`, accepting one event or an exact `{"events": [...]}` envelope, and provides collect, Freeze, Resume, Clear, and Stop; it does not own retry, deduplication, envelope identity, generation, or application lifecycle policy. While `FROZEN`, new ingest requests are rejected without writing, every dashboard continues refreshing, Clear remains available without resuming recording, and all tabs, reloads, and later analysis turns observe the same state. Correlated NDJSON is summarized by run and relevant application correlation fields before raw events are inspected. Requests to debug, troubleshoot, fix, repair, or resolve continue through the evidence-proven repair, a separate verification run, ledger completion, and cleanup unless the user explicitly requests diagnosis-only work.
02
When to use it
- 01Expensive, flaky, timing-sensitive, destructive, environment-specific, or user-only reproductions.
- 02Runtime failures that are easy to guess about but hard to prove across causal boundaries.
- 03Attached-debugger investigations that should install a broad first-pass breakpoint batch before execution resumes.
- 04Investigations that need a deterministic coverage gate before adding broad temporary instrumentation.
- 05Concurrent or distributed flows that need parent-flow, operation, request, attempt, and ordering evidence.
- 06Browser investigations that conditionally require complete page-lifetime application-fetch capture.
- 07SSE, WebSocket, subscription, long-poll, or ReadableStream failures where the business flow intentionally remains open.
- 08End-to-end bug-fix requests that must not stop at a root-cause report or unverified recommendation.
03
How it works
- 01
Resolve scope without redundant approval, default each runtime run to a user handoff, allow a pre-run agent assignment to cover the remaining autonomous chain, and require explicit run-scoped delegation for later ownership changes; then define the failure contract plus terminal or bounded observation condition and inspect the relevant execution path.
- 02
Build a causal-boundary map and enumerate code-grounded material hypotheses with both confirming and rejecting evidence.
- 03
Create and validate one coverage-plan file whose debugger strategy, initial and deferred breakpoints, boundaries, hypotheses, probes, fixed all-occurrences/every-execution cardinality, structured payload-only bounds, privacy checks, and residual ambiguities agree; unknown keys are rejected structurally, and mandatory semantic review rejects token breakpoint batches or prose that tries to override occurrence policy.
- 04
When a native debugger is attached and pausing is safe, install every safe nonredundant initial breakpoint before the first run or continue, issuing single-location calls back-to-back; after a pause, add the entire newly justified causal-interval batch before resuming. Use non-pausing probes when suspension is unsafe.
- 05
Read the investigation ledger and resume its exact active ready file before any start attempt; reuse a healthy collector and dashboard across turns and run IDs without workspace scanning or UI reopening, and replace it only when missing or unreachable or when the user or host explicitly requires isolation or replacement.
- 06
Instrument shared causal cuts and invariants, select a project logger or runtime-native adapter, resolve every temporary helper reference independently with the target project's module system (optionally using the path helper for slash-delimited file-relative references), and pass native resolution, compile, collector, expected-probe, and cardinality gates; then after prior frozen analysis and next-run preparation run `resume-recording`, require collector recording to be live, and copy the normalized `dashboard-status` line before every user-owned reproduction.
- 07
Collect one clean terminal run or bounded observation window. Interpret the user's reply in context to recognize a completed handoff without requiring a fixed phrase, then detach producers, flush the selected logger or runtime adapter, reconcile accepted writes with persisted NDJSON, freeze the collector, and summarize evidence by run and relevant application correlation fields while recording remains frozen.
- 08
Prove origin-to-symptom propagation or add only probes for the smallest unresolved causal interval, updating one evolving investigation ledger throughout.
- 09
For diagnosis-only work, preserve evidence and clean temporary instrumentation before reporting; otherwise treat diagnosis as intermediate, repair the proven mechanism immediately, verify separately, and then clean owned artifacts.
04
What you get back
- 01A validated machine-readable coverage plan containing the debugger decision, broad initial/deferred breakpoint batch, and structured probes, shared by location sync and expected-probe analysis.
- 02A cited origin-to-symptom proof or the smallest explicitly unresolved causal interval.
- 03For continuous streams, a persisted bounded source-prefix checkpoint and source-gap report that closes the evidence window without claiming the business stream ended.
- 04One evolving investigation ledger, including active collector and session history, for every repair-scoped, user-owned, multi-run, or durable investigation.
- 05Scannable Markdown handoffs for user-owned reproduction, evidence analysis, and repair verification, with blank-line-separated headings and lists.
- 06For repair-scoped work, a causally sufficient code change backed by a separate verification run and deterministic cleanup.
05
Important boundaries
- 01Do not claim a root cause without evidence for the originating fault, its propagation, and the reported symptom.
- 02Do not resume after installing only one or two native breakpoints when more safe nonredundant first-pass locations are already justified; install the full batch or record each explicit deferral.
- 03Do not count a pause-only breakpoint as an all-occurrence structured probe or use a non-hit alone to prove absence.
- 04Do not use raw debugger-console logpoints as complete evidence; an evidence-bearing logpoint must also be a validated structured probe routed through the selected runtime adapter.
- 05Do not rewrite completed run ownership or interpret a request to analyze completed evidence as delegation of a future reproduction; require an explicit run-scoped directive for ownership changes.
- 06Do not start a second collector or reopen its dashboard after the ledger's exact active ready file resumes successfully; a user reply, analysis turn, context compaction, repair phase, or new run ID is not a collector-session boundary.
- 07Do not scan the workspace for a session to resume; replace only a missing or unreachable recorded session or under an explicit user or host isolation/replacement directive, and record the transition in the same investigation ledger.
- 08Do not treat user-owned reproduction, missing agent browser control, or a ban on agent-operated product browsing as a headless reason to disable local dashboard auto-open.
- 09Do not add a correlation header when it could change CORS, cache, routing, signing, authorization, or product behavior.
- 10Do not treat dashboard visibility as evidence or let a failed open block evidence collection or reproduction.
- 11Do not invent a DevTools or page-global helper as a user completion action; attach checkpoint instrumentation to the natural boundary and use an existing host action or a natural-language report. Evaluate the whole reply's intent rather than matching keywords, and verify the checkpoint, acknowledgements, and persisted records independently of user-reported completion.
- 12Do not treat collector-global `FROZEN` as health failure, evidence completion, or a persistence checkpoint, and never Freeze before producers are detached and the selected adapter is flushed; keep recording frozen through analysis and repair, then Resume only after the next run is prepared and immediately before recording.
- 13Do not apply a repair when the request is diagnosis-only or retain a smaller workaround that leaves the causal mechanism active.
- 14Do not sample, throttle, debounce, first-N, change-gate, once-per-key, aggregate, merge, coalesce, overwrite, deduplicate, or discard any active probe occurrence.
- 15Do not require the target project to import a bundled language-specific transport, fire and forget collector writes, or automatically retry an ambiguous response under an assumed deduplication guarantee.
- 16Do not guess or copy a relative helper reference across differently nested importers; create the target first and require the target project's native resolver or compiler to accept every temporary cross-file edge.
- 17Do not claim lossless coverage across reload, navigation, process loss, memory exhaustion, or storage exhaustion without an authoritative durable producer-side logger.
- 18Do not analyze unbounded raw logs before summarization or leave temporary instrumentation and owned artifacts after successful cleanup.
06