Team Learning Goal
Teach markers as human-intent anchors in debugging workflows.
By the end of this section, the room should understand:
- why raw logs are not enough
- how
mark -> capture -> explain -> review/exportworks - what a
DebugSession,DebugMoment,CapturedEvent, andnearbyEventIdsare - how to export marker JSON from browser/dev/test flows
- how privacy defaults prevent overcapture
- how marker exports become bounded debug packets
- how Section 9 can use the packet as a work unit
Walkthrough Depth
Essential Walkthrough
- State: raw logs tell what emitted; markers tell why a moment mattered.
- Draw
mark -> capture -> explain -> review/export. - Show
createAgentMarkers. - Show
window.__AGENT_MARKERS__.markandexport. - Show the final agent prompt shape.
Expanded Walkthrough
Add:
- capture types table
- privacy defaults
nearbyEventIds- Playwright export
stop()cleanup
Deep-Dive Walkthrough
Add:
- app-specific
Ctrl+Mflow - bounded replay capsule
- smoke/test commands
- exercises
Talking Points
Opening:
Raw logs tell you what emitted. Agent markers tell you why a moment mattered.
On markers:
A marker is a human-intent anchor, not another log line.
On privacy:
Metadata first. Values only when deliberately enabled and safe.
On replay:
This is a bounded debug packet, not a deterministic recorder.
Bridge from Section 7:
Section 7 preserved evidence from video. Section 8 lets you create evidence while debugging.
Bridge to Section 9:
A good marker export is small enough to become a work unit.
Live Demo Script
1. Show Setup
import { createAgentMarkers } from "@agent-markers/client";
const markers = createAgentMarkers({
appName: "checkout-app",
exposeGlobal: true,
capture: {
console: true,
fetch: true,
errors: true,
},
});
2. Create A Marker
window.__AGENT_MARKERS__.mark({
label: "saved payment selector empty after refresh",
note: "Expected saved cards to stay visible after auth refresh; actual selector is empty.",
});
3. Export
const session = window.__AGENT_MARKERS__.export();
({
markerCount: session.markers.length,
eventCount: session.events.length,
hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),
});
4. Verify Project
npm test
npm run typecheck
npm run build
npm run smoke:demo
Minimal Useful Path
If 5 minutes behind, cut:
- Cypress example
- app-specific
Ctrl+M - bounded replay capsule details
- screenshot/DOM hook implementation
Preserve:
mark -> capture -> explain -> review/exportcreateAgentMarkerswindow.__AGENT_MARKERS__nearbyEventIds- privacy defaults
- export JSON
- Section 9 bridge
Boundaries
From Section 7
Section 7:
source media -> evidence lanes -> verified prompt material
Section 8:
marked moment -> nearby runtime evidence -> bounded debug packet
To Section 9
Section 9 needs work units that are small, bounded, and verifiable.
Agent markers provide:
- one marker id
- human explanation
- nearby evidence
- privacy boundary
- verification command
- next action
Failure Paths To Preserve
No note:
A marker without a human explanation is just another timestamp.
Too many logs:
Focus on one marker id and nearby events.
Sensitive storage:
Redact and rebuild. Metadata first.
No nearby events:
Mark closer to the failure or adjust the nearby window deliberately.
Patched APIs not restored:
Call
stop()and test cleanup.
No test export:
Expose the global in dev/test and wait for app readiness.
Team Checklist
Confirm the materials include:
mark -> capture -> explain -> review/export
createAgentMarkers
DebugSession
DebugMoment
CapturedEvent
nearbyEventIds
console capture
fetch capture
error capture
manual evidence
DOM hook
screenshot hook
privacy defaults
storage metadata
window.__AGENT_MARKERS__
export JSON
download
stop()
npm test
npm run typecheck
npm run build
npm run smoke:demo
Playwright export
Cypress export
dev_marker
dev_marker_explanation
bounded replay capsule
Section 9 bridge
Further References
- team-facing file:
cheatsheets/08-debugging-with-agent-markers.md - Exercises:
exercises/08-debugging-with-agent-markers.md - Agent marker client:
packages/client/src/index.ts - Collector:
packages/client/src/collector.ts - Demo:
apps/demo/src/main.ts - Smoke script:
scripts/smoke-demo.mjs