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: