Agent Markers debugging workflows: team walkthrough

Marker-centered debugging using createAgentMarkers, browser-global marking and export, nearby-event association, privacy boundaries, cleanup, and project verification. Preserves the bounded debug-packet model, downstream work-unit bridge, failure recovery,…

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/export works
  • what a DebugSession, DebugMoment, CapturedEvent, and nearbyEventIds are
  • 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

  1. State: raw logs tell what emitted; markers tell why a moment mattered.
  2. Draw mark -> capture -> explain -> review/export.
  3. Show createAgentMarkers.
  4. Show window.__AGENT_MARKERS__.mark and export.
  5. 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+M flow
  • 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/export
  • createAgentMarkers
  • window.__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

Source references