{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-debug-markers-questions",
  "slug": "debug-markers-questions",
  "title": "Human testimony joined to runtime evidence — questions and tradeoffs",
  "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Verification",
  "tags": [
    "debug-markers",
    "questions"
  ],
  "sources": [
    {
      "label": "Human testimony joined to runtime evidence — questions and tradeoffs",
      "url": "https://mindful-mango-accy.here.now/dialogue.html"
    }
  ],
  "sourceUnits": [
    "09-markers/dialogue.html#section-1"
  ],
  "collection": "factory",
  "categoryId": "verification",
  "wordCount": 1072,
  "url": "/topics/factory-debug-markers-questions/",
  "markdownUrl": "/markdown/factory-debug-markers-questions.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-debug-markers-questions.json",
  "headings": [],
  "markdown": "# Human testimony joined to runtime evidence — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\nIsn’t this just logging? I already have logs.\n\nLogs 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:\n\n``` text\n## Human testimony (why this moment matters)\n\n> It said Saved but my note never reached the server — this happened right after I reconnected.\n```\n\nThe testimony points into the trail; the trail grounds the testimony in ordered facts. Neither alone does the job.\n\nWill anyone actually press the button? My users don’t even file bug reports.\n\nThat'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:\n\n``` text\n/* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.\n   Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */\nAgentMarkers.start({ app: \"my-app\" }); // replace \"my-app\" with your app's name\n\n// One keystroke at the moment of surprise: one sentence of testimony.\nwindow.addEventListener(\"keydown\", (e) => {\n  if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === \"m\") {\n    e.preventDefault();\n    const note = prompt(\"Why does this moment matter? (one sentence — it travels with the capture)\");\n    if (note !== null) console.log(\"marked:\", AgentMarkers.mark(\"user-flag\", note).id);\n  }\n});\n\n// Call exportMarkers() from the console, or wire it to a button.\nwindow.exportMarkers = () => {\n  const session = AgentMarkers.exportSession();\n  const blob = new Blob([JSON.stringify(session, null, 2)], { type: \"application/json\" });\n  const a = Object.assign(document.createElement(\"a\"), {\n    href: URL.createObjectURL(blob),\n    download: session.sessionId + \".json\",\n  });\n  a.click();\n  URL.revokeObjectURL(a.href);\n  return session.sessionId + \".json\";\n};\n```\n\nYou’re recording my users’ clicks and network calls. Legal will kill this.\n\nOnly 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:\n\n``` text\n## Redaction receipts\n\n- storageValues: excluded\n- requestBodies: excluded\n- responseBodies: excluded\n- userText: preview+length only\n```\n\nNo 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.\n\nNine events? My log dump has fifty thousand lines. How is less data better?\n\nBecause 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:\n\n``` text\n- [seq 3 · t+17397ms] click: click <button#save> \"Save note\"\n- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]\n- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable\n- [seq 6 · t+18436ms] click: click <button#toggle-net> \"Reconnect\"\n- [seq 7 · t+18436ms] console: console.log: reconnected: session restored\n- [seq 8 · t+18909ms] click: click <button#save> \"Save note\"\n- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]\n```\n\nNetwork 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](https://mindful-mango-accy.here.now/replay.html) shows the whole run that produced it.\n\nSo the agent reads that and confidently guesses anyway. How is this not garbage in, gospel out?\n\nThe 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:\n\n``` text\nHere is a debug packet captured from a live session of my app. Before you read any code:\n\n1. Read the human testimony, then the evidence trail in seq order.\n2. State your single most likely hypothesis for the failure, in one sentence.\n3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet.\n4. Label anything the trail cannot prove as \"hypothesis — needs verification\".\n\nTestimony is not diagnosis. Context is not proof.\n\n--- PACKET ---\n[paste the output of: node scripts/make-agent-packet.mjs your-session.json]\n```\n\nThe 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.\n\nCute demo. Does this survive contact with a real app?\n\nIt'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.\n\nOne 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.\n\nFine. What do I paste into my project right now?\n\nTwo options. See the loop run cold from an empty directory in about thirty seconds:\n\n``` text\nmkdir -p markers-quickstart && cd markers-quickstart\ncurl -sO https://mindful-mango-accy.here.now/agent-markers.js\ncurl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode make-agent-packet.mjs sample-session.json\n```\n\nOr skip the typing entirely — paste this into your own agent and let it wire your app:\n\n``` text\nFetch 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.\n```\n\nThe [section guide](https://mindful-mango-accy.here.now/index.html) prints all three files complete — recorder, boot, packet renderer."
}
