Evidence-First Debugging

Core Rules

1. Build the evidence chain before proposing a root cause.
2. Runtime evidence beats static code inference. Static code shows what could happen; logs, traces, network data, screenshots, or reproducible output show what did happen.
3. Keep speculation to one step. Do not chain "maybe A, therefore maybe B, therefore root cause C".
4. If the user challenges your hypothesis, look for missing evidence first instead of immediately switching to another hypothesis.
5. If evidence is insufficient, say so plainly and add the smallest useful temporary instrumentation before changing business logic.
6. Do not use strong wording such as "confirmed", "locked", "definitive", or "closed evidence chain" unless the key runtime evidence has been checked.
7. Validate write paths with write evidence. A read path that looks consistent with your hypothesis does not prove where data should be written. Reads may succeed through getters, fallbacks, proxies, prototype chains, lazy migration shims, or framework behavior that does not apply to writes. Before committing a write-path fix, find a working write call site, the deserialization/initialization path that proves where data lives at rest, or the persistence/save path that proves what the system later reads. If you only have read-path inference, label it as a current hypothesis.
8. Treat temporary instrumentation as a lifecycle, not a deliverable. Add it to collect evidence, use it to confirm or reject the hypothesis, then remove it after the issue is fixed or the user confirms the issue is fixed unless there is an explicit decision to keep it behind a safe debug gate.

Evidence Table

Evidence source | Checked? | Type | What it proves | Strength
User repro steps | yes/no | runtime artifact | ... | weak/medium/strong
Browser console/network/DOM | yes/no | runtime | ... | weak/medium/strong
Node.js/server log | yes/no | runtime | ... | weak/medium/strong
CLI/test/CI output | yes/no | runtime | ... | weak/medium/strong
Relevant code path | yes/no | static inference | ... | weak/medium/strong

• Confirmed fact: directly observed in runtime evidence or reproduced.
• Strong inference: multiple evidence sources agree, but one direct signal is missing.
• Current hypothesis: plausible from available evidence, but still needs validation.
• Unverified assumption: do not use as the basis for a fix.

Fix Gate

• If a key runtime source is unchecked, prefer instrumentation over a speculative fix.
• If only static code reading supports the hypothesis, label it as a hypothesis.
• If the issue can be reproduced locally, reproduce it and capture output before editing.
• If the issue cannot be reproduced, add temporary logs that the agent or user can retrieve after one reproduction.
• If the fix changes a write, mutation, or persistence path, do not ship based only on a matching read path. Require either a working write-path analog in the same codebase, or a runtime/integration check proving the written data is observable through the system's actual read, save, or downstream consumption path.
• If you added temporary instrumentation and the issue is later fixed or verified, remove the instrumentation before finishing unless the user explicitly wants to keep it. If kept, gate it, document why, and ensure it is safe for normal usage.

Temporary Instrumentation

• Use a stable prefix or event name, such as

  [checkout-debug]

  .
• Include timestamp and a correlation id when available: request id, session id, trace id, job id, route, or component name.
• Capture branch decisions, input summary, output summary, validation results, stop/skip reasons, and error details.
• Avoid secrets, tokens, cookies, authorization headers, raw PII, and huge payloads.
• Prefer structured JSON or JSONL over prose.
• Be easy to remove, downgrade behind a debug flag, or keep only in local/dev paths after the issue is fixed.

1. Add the smallest behavior-preserving instrumentation needed around the missing evidence.
2. Collect evidence through a reproduction.
3. Read and interpret the collected logs.
4. Use the evidence to confirm, reject, or revise the hypothesis.
5. Fix and verify the issue.
6. Remove the temporary instrumentation after verification or after the user confirms the issue is fixed. Keep it only if there is an intentional debug-only decision.

Node.js Logging Pattern

/tmp/<project-or-feature>-debug.jsonl

.debug/<feature>.jsonl

import fs from "node:fs";

const DEBUG_LOG_PATH =
  process.env.FEATURE_DEBUG_LOG || "/tmp/feature-debug.jsonl";

function summarizeDebugValue(value: unknown): unknown {
  if (value instanceof Error) {
    return {
      name: value.name,
      message: value.message,
      stack: value.stack,
    };
  }

  try {
    return JSON.parse(JSON.stringify(value));
  } catch {
    return { unserializable: true, type: typeof value };
  }
}

export function debugEvent(event: string, payload: Record<string, unknown>) {
  const record = {
    ts: new Date().toISOString(),
    event,
    ...Object.fromEntries(
      Object.entries(payload).map(([key, value]) => [
        key,
        summarizeDebugValue(value),
      ]),
    ),
  };

  fs.appendFileSync(DEBUG_LOG_PATH, JSON.stringify(record) + "\n");
}

• External input boundary: request payload summary, job input, tool input, or message metadata.
• Before and after important branch decisions.
• Schema parse, validation, permission, feature flag, or route matching results.
• Before and after calls to external services, providers, databases, queues, or tools.
• Early return, short-circuit, skip, retry, fallback, or error paths.

node:fs

Node.js Self-Closure

1. Add temporary JSONL instrumentation.
2. Clear or rotate the old debug log so the next run is easy to inspect.
3. Run the repro command yourself, such as

   curl

   , an npm script, a CLI command, or a focused test.
4. Read the local log file yourself.
5. Update the evidence table before changing the fix direction.

Browser Logging Pattern

type BrowserDebugRecord = {
  ts: string;
  event: string;
  [key: string]: unknown;
};

declare global {
  interface Window {
    __featureDebugEvents?: BrowserDebugRecord[];
  }
}

function toDebugSnapshot(value: unknown): unknown {
  if (value instanceof Error) {
    return {
      name: value.name,
      message: value.message,
      stack: value.stack,
    };
  }

  try {
    return JSON.parse(JSON.stringify(value));
  } catch {
    return { unserializable: true, type: typeof value };
  }
}

export function debugBrowserEvent(
  event: string,
  payload: Record<string, unknown> = {},
) {
  const record: BrowserDebugRecord = {
    ts: new Date().toISOString(),
    event,
    ...Object.fromEntries(
      Object.entries(payload).map(([key, value]) => [
        key,
        toDebugSnapshot(value),
      ]),
    ),
  };

  window.__featureDebugEvents ||= [];
  window.__featureDebugEvents.push(record);
  window.__featureDebugEvents = window.__featureDebugEvents.slice(-100);

  console.debug("[feature-debug]", JSON.stringify(record));
}

copy(JSON.stringify(window.__featureDebugEvents || [], null, 2))

• Console errors and debug events.
• Network request URL, method, status, request summary, and response summary.
• Actual DOM/UI state after the action.
• Whether event handlers, effects, callbacks, route changes, or async completions ran.
• Browser screenshots only when visual state matters.

Privacy And Payload Safety

• hasAuthorizationHeader: true

  , never the header value.

• emailHash

  or

  emailDomain

  , not raw email unless essential and approved.

• payloadKeys

  ,

  arrayLength

  ,

  status

  ,

  errorName

  ,

  errorMessage

  ,

  route

  ,

  featureFlagValue

  .
• Truncated strings and sampled arrays when payloads are large.

Output Format

已确认事实:
...

代码推断:
...

当前假设:
...

缺失证据:
...

下一步:
...

• Where the log is written or how to copy it.
• What action the user should reproduce.
• What evidence you expect the log to confirm or rule out.
• Whether the agent can self-run the reproduction and read the log, or whether the user must reproduce in the browser.
• The cleanup action taken after the fix, or the reason a debug-gated log remains.

Anti-Patterns

• Declaring a root cause from code reading alone.
• Ignoring user-provided runtime evidence because the code "should" behave differently.
• Switching hypotheses after a user challenge without identifying the missing evidence.
• Adding broad noisy logs instead of targeted logs around the decision point.
• Logging raw secrets or large user payloads.
• Leaving temporary instrumentation in production paths without a debug gate or cleanup plan.
• Asking the user to paste Node.js, CLI, or server logs that the agent can read locally after running the provided reproduction command.
• Finishing after the user says the issue is fixed while leaving temporary instrumentation in place without removing it or explicitly gating it.
• Inferring a write API from a read call site without checking sibling write handlers, mutation handlers, serializers, or save paths in the same module.
• Treating a mocked unit test as proof of business correctness. A mock confirming

  obj.method()

  was called proves the interaction happened, not that the method writes to the location the rest of the system reads from.
• Accepting a test that only verifies the local code path when the real contract is whether persisted or mutated state is observable from the actual downstream read path.