Agent Markers debugging workflows: practice drills

Exercises for marking browser failures, initializing Agent Markers, exporting bounded evidence, reviewing privacy, attaching exports to tests, verifying projects, writing debug prompts, designing replay capsules and app-specific shortcuts, recovering from…

These exercises practice creating a bounded debug packet from a marked browser moment.

Exercise 1: Identify The Marker Moment

Choose a bug and write the marker.

# Marker Moment

- app area:
- expected:
- actual:
- why this moment matters:
- next action:
- what nearby evidence should be captured:

Good marker:

{
  "label": "saved payment selector empty after refresh",
  "note": "Expected saved cards to stay visible after auth refresh; actual selector is empty.",
  "nextAction": "Compare account payment fetch response with checkout payment state."
}

Exercise 2: Add The Client

Sketch the setup:

import { createAgentMarkers } from "@agent-markers/client";

const markers = createAgentMarkers({
  appName: "checkout-app",
  exposeGlobal: true,
  capture: {
    console: true,
    fetch: true,
    errors: true,
  },
});

Fill out:

# Client Setup

- app name:
- exposeGlobal enabled? yes/no
- console capture? yes/no
- fetch capture? yes/no
- error capture? yes/no
- privacy concern:

Exercise 3: Create And Export A Marker

Run in browser console or test:

window.__AGENT_MARKERS__.mark({
  label: "checkout failure",
  note: "Expected saved cards to render before submit.",
  nextAction: "Inspect checkout payment query and auth refresh state.",
});

const session = window.__AGENT_MARKERS__.export();
JSON.stringify(session, null, 2);

Fill out:

# Marker Export

- marker count:
- event count:
- marker label:
- marker note:
- nearbyEventIds present? yes/no
- event types:

Exercise 4: Privacy Review

Inspect the export.

const session = window.__AGENT_MARKERS__.export();
({
  schemaVersion: session.schemaVersion,
  markerCount: session.markers.length,
  eventCount: session.events.length,
  storageHasValues: JSON.stringify(session).includes("secret-value"),
});

Fill out:

# Privacy Review

- storage keys captured:
- storage values captured? yes/no
- request bodies captured? yes/no
- response bodies captured? yes/no
- private text present? yes/no
- redaction needed:

Exercise 5: Test Runner Export

Playwright-style shape:

const session = await page.evaluate(() => window.__AGENT_MARKERS__.export());

await testInfo.attach("agent-markers.json", {
  body: JSON.stringify(session, null, 2),
  contentType: "application/json",
});

Fill out:

# Test Export

- test command:
- export artifact:
- marker count:
- nearbyEventIds present? yes/no
- test can access global? yes/no
- app readiness check:

Exercise 6: Verify The Project

Run:

npm test
npm run typecheck
npm run build
npm run smoke:demo

Fill out:

# Verification

- npm test:
- npm run typecheck:
- npm run build:
- npm run smoke:demo:
- failed command:
- next debugging step:

Exercise 7: Turn Export Into A Debug Prompt

Write:

# Debug Prompt From Agent Marker

## Source Artifact

- marker export:
- schema version:
- marker id:
- marker label:

## Human Explanation

- expected:
- actual:
- why this moment matters:
- next action:

## Nearby Evidence

- console:
- fetch:
- error:
- manual:
- screenshot:
- DOM:

## Privacy Boundary

- storage values exported? no
- request bodies exported? no
- response bodies exported? no
- private text removed:

## Task

Find the smallest likely bug path and propose the first verification command.
Do not invent app state that is not in the marker packet.

Exercise 8: Design A Bounded Replay Capsule

Do not implement a recorder. Design the packet.

# Bounded Replay Capsule

- schemaVersion:
- markerId:
- sessionId:
- markerCutoffSeq:
- nearbyEventIds:
- console:
- fetch:
- errors:
- manual:
- screenshot:
- dom:
- redaction:

## Boundaries

- included:
- excluded:
- maximum event count:
- privacy rules:

## How To Use It

- agent prompt:
- human review:
- verification command:

Question:

What is the smallest capsule that would let someone debug the marked moment?

Exercise 9: App-Specific Marker Flow

Inspect or design a shortcut flow.

Ctrl+M
-> create marker id
-> capture screenshot if available
-> open note/explanation UI
-> save human explanation
-> write durable app logs

Possible inspection command:

rg -n "dev_marker|dev_marker_explanation" <app-log-path>/latest-session.jsonl

Fill out:

# App-Specific Marker Flow

- shortcut:
- marker id format:
- screenshot available? yes/no:
- explanation UI:
- log path:
- `dev_marker` written? yes/no:
- `dev_marker_explanation` written? yes/no:
- shared marker id? yes/no:
- what this preserves:
- what this does not try to solve:

Exercise 10: Failure Path Drill

For each failure, choose a recovery.

Failure Recovery
marker has no note
export has thousands of raw log entries
marker has empty nearbyEventIds
exported JSON contains sensitive storage values
console/fetch remains patched after test
Playwright cannot read window.__AGENT_MARKERS__
marker does not say what to inspect next
screenshot hook returns nothing
DOM snapshot includes private text
smoke test fails before clicking marker buttons

Recovery options:

add expected/actual note
focus on one marker id
mark closer to the failure
raise nearbyEventLimit deliberately
redact and rebuild export
restore with stop()
enable exposeGlobal in dev/test
wait for app readiness
add next action
mark screenshot unavailable
narrow DOM snapshot
save failed smoke and retry with sharper condition

Exercise 11: Section 9 Bridge Packet

Use one marker export to prepare a bounded work unit.

# Section 9 Bridge: Imp Debug Packet

- source artifact: DebugSession export
- schemaVersion:
- marker id:
- marker label:
- marker note:
- nearbyEventIds:
- evidence lanes:
  - console:
  - fetch:
  - error:
  - manual:
- privacy checks:
  - storageHasValues:
  - request bodies exported? no
  - response bodies exported? no
- likely app area:
- required verification:
  - npm test
  - npm run typecheck
  - npm run build
- next action:

Fill out:

# Bridge Review

- packet names one marker id? yes/no:
- nearby evidence is bounded? yes/no:
- privacy rules are explicit? yes/no:
- verification commands are present? yes/no:
- task is clear enough for an Imp? yes/no:
- what would make it smaller or sharper:

Final Check

Inspect manually:

const session = window.__AGENT_MARKERS__.export();
({
  schemaVersion: session.schemaVersion,
  markerCount: session.markers.length,
  eventCount: session.events.length,
  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),
  eventTypes: [...new Set(session.events.map((event) => event.type))],
});

Fill out:

# Final Agent Markers Check

- marker created? yes/no:
- marker has human explanation? yes/no:
- nearbyEventIds present? yes/no:
- console evidence captured? yes/no:
- fetch evidence captured? yes/no:
- error evidence captured? yes/no:
- manual evidence captured? yes/no:
- storage values avoided? yes/no:
- export saved? yes/no:
- test runner can export? yes/no:
- `stop()` cleanup handled? yes/no:
- next action written? yes/no:
- ready to hand off as bounded debug packet? yes/no:

Source references