Agentic Software Factory · 2026-07-17 · Debugging with Markers

“Isn’t this just logging?”

The section as the workshop room actually runs it: skeptical questions drive the reveal. Each answer lands the real code exactly where the question demands it.

Isn’t this just logging? I already have logs.

Logs are complete but unweighted — nothing in fifty thousand lines says this is the moment that mattered. When a person watching the app says "that was wrong," that sentence is the highest-value debugging signal we have, and we normally throw it away. A marker makes it a first-class, timestamped artifact: one sentence of testimony, pinned to the ids of the nearest events. Here's the one from this site's real capture, exactly as the packet renders it:

## Human testimony (why this moment matters)

> It said Saved but my note never reached the server — this happened right after I reconnected.

The testimony points into the trail; the trail grounds the testimony in ordered facts. Neither alone does the job.

Will anyone actually press the button? My users don’t even file bug reports.

That's the design constraint the whole thing is built around: one keystroke, one sentence, during the surprise. No form, no repro steps demanded. Anything heavier and nobody uses it at the moment that matters. The entire user-facing surface is this boot file — Ctrl/Cmd+M to mark, one console call to export:

/* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.
   Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */
AgentMarkers.start({ app: "my-app" }); // replace "my-app" with your app's name

// One keystroke at the moment of surprise: one sentence of testimony.
window.addEventListener("keydown", (e) => {
  if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "m") {
    e.preventDefault();
    const note = prompt("Why does this moment matter? (one sentence — it travels with the capture)");
    if (note !== null) console.log("marked:", AgentMarkers.mark("user-flag", note).id);
  }
});

// Call exportMarkers() from the console, or wire it to a button.
window.exportMarkers = () => {
  const session = AgentMarkers.exportSession();
  const blob = new Blob([JSON.stringify(session, null, 2)], { type: "application/json" });
  const a = Object.assign(document.createElement("a"), {
    href: URL.createObjectURL(blob),
    download: session.sessionId + ".json",
  });
  a.click();
  URL.revokeObjectURL(a.href);
  return session.sessionId + ".json";
};
You’re recording my users’ clicks and network calls. Legal will kill this.

Only if you capture what legal is worried about — so don't. Decide the exclusions before the first capture, write them into the payload itself, and accept the narrower evidence. Every export from the recorder carries its own receipts:

## Redaction receipts

- storageValues: excluded
- requestBodies: excluded
- responseBodies: excluded
- userText: preview+length only

No bodies, no tokens, no storage values; user text as preview + length only. A capture safe enough to paste anywhere gets pasted. A risky one gets hoarded and helps no one.

Nine events? My log dump has fifty thousand lines. How is less data better?

Because the slice is chosen by the human's testimony, not by grep luck. Read the real one from this site's captured session and name the bug before anyone tells you:

- [seq 3 · t+17397ms] click: click <button#save> "Save note"
- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]
- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable
- [seq 6 · t+18436ms] click: click <button#toggle-net> "Reconnect"
- [seq 7 · t+18436ms] console: console.log: reconnected: session restored
- [seq 8 · t+18909ms] click: click <button#save> "Save note"
- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]

Network failure, a "session restored" log, then a 401 on the very next save — under a UI that said "Saved ✓". If you just reached "the reconnect invalidated something the client still holds," a nine-line slice did what the dump rarely does. The Session Replay shows the whole run that produced it.

So the agent reads that and confidently guesses anyway. How is this not garbage in, gospel out?

The handoff carries a fence. A weak handoff pastes a dump and asks "what's wrong?" — inviting confident guessing over noise. A strong handoff gives less data and more structure: what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. This is the exact prompt I hand any agent with a packet:

Here is a debug packet captured from a live session of my app. Before you read any code:

1. Read the human testimony, then the evidence trail in seq order.
2. State your single most likely hypothesis for the failure, in one sentence.
3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet.
4. Label anything the trail cannot prove as "hypothesis — needs verification".

Testimony is not diagnosis. Context is not proof.

--- PACKET ---
[paste the output of: node scripts/make-agent-packet.mjs your-session.json]

The packet itself ends the same way — a claims boundary. The agent's draft arrives labeled as a draft, and a person verifies it against the running app.

Cute demo. Does this survive contact with a real app?

It's already shipped. A production desktop app we studied runs the same loop natively: a hotkey mints a marker id, captures a screenshot, writes a marker log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose --marker flag slices the session for agents. An external architecture review of that system pushed the same schema rules this recorder uses: sequence numbers as canonical order (not timestamps), ids joining everything, user text as preview + hash + length — never raw.

One integration gotcha from real use: if your app wraps fetch (mocks, auth shims), install your wrapper before AgentMarkers.start() so the wrapped calls land in the trail.

Fine. What do I paste into my project right now?

Two options. See the loop run cold from an empty directory in about thirty seconds:

mkdir -p markers-quickstart && cd markers-quickstart
curl -sO https://mindful-mango-accy.here.now/agent-markers.js
curl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs
curl -sO https://mindful-mango-accy.here.now/sample-session.json
node make-agent-packet.mjs sample-session.json

Or skip the typing entirely — paste this into your own agent and let it wire your app:

Fetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.

The section guide prints all three files complete — recorder, boot, packet renderer.