Capture the moment of surprise with a bounded redacted trail and discriminate between hypotheses before changing code.
Related working material
- Human testimony joined to runtime evidence — prompts and exercises
- Human testimony joined to runtime evidence — questions and tradeoffs
- Human testimony joined to runtime evidence — worked example
TL;DR
- A ~150-line, dependency-free recorder (
agent-markers.js, printed complete below) logs clicks, fetches, console lines, and errors into a bounded ring buffer in any web app. - One keystroke pins one sentence of human testimony to the nearest events; one call exports a redacted JSON payload safe to paste anywhere — no bodies, no tokens, no raw user text.
- The move: mark at the moment of surprise, render the export into a debug packet, and make the agent state a hypothesis before it reads any code.
Have your agent set this up — paste this into it:
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 signal you normally throw away
You are testing an app. Something feels off — a stale value, a success message you do not believe. Usually that judgment evaporates: hours later someone asks for a bug report, and you reconstruct the moment from memory, losing the timing, the order of actions, and most of the value. The pattern this session builds on calls human intent “the missing signal” in agent debugging and records it the moment it occurs.
This is not a paper idea. A production desktop app we studied ships the same move: a hotkey mints a marker id, captures a screenshot, writes a dev_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. The design rule that makes it work: capture happens during the surprise, one keystroke and one sentence. Anything heavier and nobody uses it at the moment that matters.
A capture has two parts that answer different questions. A marker says why this moment deserves attention; a trail says how the tester arrived there. Testimony alone tells an agent what to look for but not when; a trail alone is complete but unweighted. Paired, the testimony points into the trail, and the trail grounds the testimony in ordered facts. Treat the marker as a search warrant, not a verdict.
One captured failure, read cold
The workshop demo plants a bug worth marking: a notes app goes offline, reconnects, and saves. The server rotated its session token during the reconnect; the client kept its stale copy; the save handler treats any status below 500 as success. The user sees “Saved ”. The server said 401. We drove that path in a real browser, pressed mark, and typed: “It said Saved but my note never reached the server — this happened right after I reconnected.” Seven consecutive lines of the captured trail, exactly as the packet renderer printed them:
- [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]
Read it top to bottom and name a hypothesis before anyone tells you: a network failure, a “session restored” log, then a 401 on the very next save under a visible “Saved ”. If you reached “the reconnect invalidated something the client still holds,” a nine-line slice just did what a full log dump rarely does — and an agent reads it the same way you just did.
What the capture leaves out
The moment you say “capture the entire state of the app,” you have a privacy decision, because the payload will leave your machine — pasted into an agent, attached to a ticket, shared in chat. Decide the exclusions before the first capture, write them into the payload itself, and accept the narrower evidence. The demo’s export embeds exactly this policy, so every reader can audit what was withheld:
{
"storageValues": "excluded",
"requestBodies": "excluded",
"responseBodies": "excluded",
"userText": "preview+length only"
}
An external architecture review of the production system pushed the same rule harder: order events by a sequence counter, join records by session and marker ids, and store user input as preview, hash, and length — never raw. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.
The handoff needs a fence too. A weak handoff pastes a log dump and asks “what’s wrong?”, inviting confident guessing over unweighted 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. That is why the packet ends with a claims boundary, and why the first prompt above demands a hypothesis before code: the agent’s draft arrives labeled as a draft, and a person verifies it against the running app.
Appendix
Limits & caveats
- Testimony is not diagnosis; context is not proof. The trail shows what was captured, not everything that happened — session metadata does not prove a defect, and testimony does not prove cause.
- The captured failure here is a bug we planted ourselves. The loop is demonstrated end to end, but its yield on organic bugs is untested on this page.
- Redaction trades fidelity for safety. A capture without request bodies cannot settle every question; sometimes the correct next step is a targeted, consented follow-up capture.
prompt()blocks automation. Scripted browsers should callwindow.__AGENT_MARKERS__.mark(label, note)from the console instead of the hotkey.- On macOS, Cmd+M can collide with the browser’s minimize shortcut; a page button or the console call is the reliable path.
- The ring buffer is in-memory only — a reload wipes it. Export before navigating away. Screenshots are
"unavailable"in the plain-browser recorder; the production system captures them via native APIs. - If your app installs its own
fetchwrapper (mocks, auth shims), install it beforeAgentMarkers.start()so wrapped calls land in the trail.
Operating practice
Attach testimony to runtime evidence
What to notice
Give a debugging agent the exact moment of failure, the human-observed symptom, and a bounded event trail.
Try this
Reproduce one bug, add one plain-language marker when behavior becomes wrong, and export a redacted packet for ranked hypotheses.
“I see this, and I wanna talk about that.”
John Lindquist · 02:22:16
Concept
The prepared Markers material combines human testimony with nearby console, fetch, error, and click events. That makes the next diagnostic question smaller and more discriminating.
Reflection
This module was prepared after the workshop and was not taught as a dedicated recorded section.
Recording evidence: prepared follow-up grounded in related recorded evidence.
“A lot of us spend time trying to describe bugs instead of just recording ourselves using the product.”
John Lindquist · 05:21:57