{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-marker-workflows-practice",
  "slug": "marker-workflows-practice",
  "title": "Agent Markers debugging workflows: practice drills",
  "summary": "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…",
  "category": "Verification",
  "tags": [
    "agent-markers",
    "debugging",
    "privacy",
    "practice"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 1: Identify The Marker Moment",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 2: Add The Client",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 3: Create And Export A Marker",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 4: Privacy Review",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 5: Test Runner Export",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 6: Verify The Project",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 7: Turn Export Into A Debug Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 8: Design A Bounded Replay Capsule",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 9: App-Specific Marker Flow",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 10: Failure Path Drill",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 11: Section 9 Bridge Packet",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Final Check",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "verification",
  "wordCount": 1109,
  "url": "/topics/codex-marker-workflows-practice/",
  "markdownUrl": "/markdown/codex-marker-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-marker-workflows-practice.json",
  "headings": [
    {
      "id": "exercise-1-identify-the-marker-moment",
      "text": "Exercise 1: Identify The Marker Moment",
      "level": 2
    },
    {
      "id": "exercise-2-add-the-client",
      "text": "Exercise 2: Add The Client",
      "level": 2
    },
    {
      "id": "exercise-3-create-and-export-a-marker",
      "text": "Exercise 3: Create And Export A Marker",
      "level": 2
    },
    {
      "id": "exercise-4-privacy-review",
      "text": "Exercise 4: Privacy Review",
      "level": 2
    },
    {
      "id": "exercise-5-test-runner-export",
      "text": "Exercise 5: Test Runner Export",
      "level": 2
    },
    {
      "id": "exercise-6-verify-the-project",
      "text": "Exercise 6: Verify The Project",
      "level": 2
    },
    {
      "id": "exercise-7-turn-export-into-a-debug-prompt",
      "text": "Exercise 7: Turn Export Into A Debug Prompt",
      "level": 2
    },
    {
      "id": "exercise-8-design-a-bounded-replay-capsule",
      "text": "Exercise 8: Design A Bounded Replay Capsule",
      "level": 2
    },
    {
      "id": "exercise-9-app-specific-marker-flow",
      "text": "Exercise 9: App-Specific Marker Flow",
      "level": 2
    },
    {
      "id": "exercise-10-failure-path-drill",
      "text": "Exercise 10: Failure Path Drill",
      "level": 2
    },
    {
      "id": "exercise-11-section-9-bridge-packet",
      "text": "Exercise 11: Section 9 Bridge Packet",
      "level": 2
    },
    {
      "id": "final-check",
      "text": "Final Check",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Agent Markers debugging workflows: practice drills\n\nThese exercises practice creating a bounded debug packet from a marked browser moment.\n\n## Exercise 1: Identify The Marker Moment\n\nChoose a bug and write the marker.\n\n```markdown\n# Marker Moment\n\n- app area:\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n- what nearby evidence should be captured:\n```\n\nGood marker:\n\n```json\n{\n  \"label\": \"saved payment selector empty after refresh\",\n  \"note\": \"Expected saved cards to stay visible after auth refresh; actual selector is empty.\",\n  \"nextAction\": \"Compare account payment fetch response with checkout payment state.\"\n}\n```\n\n## Exercise 2: Add The Client\n\nSketch the setup:\n\n```ts\nimport { createAgentMarkers } from \"@agent-markers/client\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n  capture: {\n    console: true,\n    fetch: true,\n    errors: true,\n  },\n});\n```\n\nFill out:\n\n```markdown\n# Client Setup\n\n- app name:\n- exposeGlobal enabled? yes/no\n- console capture? yes/no\n- fetch capture? yes/no\n- error capture? yes/no\n- privacy concern:\n```\n\n## Exercise 3: Create And Export A Marker\n\nRun in browser console or test:\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"checkout failure\",\n  note: \"Expected saved cards to render before submit.\",\n  nextAction: \"Inspect checkout payment query and auth refresh state.\",\n});\n\nconst session = window.__AGENT_MARKERS__.export();\nJSON.stringify(session, null, 2);\n```\n\nFill out:\n\n```markdown\n# Marker Export\n\n- marker count:\n- event count:\n- marker label:\n- marker note:\n- nearbyEventIds present? yes/no\n- event types:\n```\n\n## Exercise 4: Privacy Review\n\nInspect the export.\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  schemaVersion: session.schemaVersion,\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  storageHasValues: JSON.stringify(session).includes(\"secret-value\"),\n});\n```\n\nFill out:\n\n```markdown\n# Privacy Review\n\n- storage keys captured:\n- storage values captured? yes/no\n- request bodies captured? yes/no\n- response bodies captured? yes/no\n- private text present? yes/no\n- redaction needed:\n```\n\n## Exercise 5: Test Runner Export\n\nPlaywright-style shape:\n\n```ts\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\n\nawait testInfo.attach(\"agent-markers.json\", {\n  body: JSON.stringify(session, null, 2),\n  contentType: \"application/json\",\n});\n```\n\nFill out:\n\n```markdown\n# Test Export\n\n- test command:\n- export artifact:\n- marker count:\n- nearbyEventIds present? yes/no\n- test can access global? yes/no\n- app readiness check:\n```\n\n## Exercise 6: Verify The Project\n\nRun:\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\nFill out:\n\n```markdown\n# Verification\n\n- npm test:\n- npm run typecheck:\n- npm run build:\n- npm run smoke:demo:\n- failed command:\n- next debugging step:\n```\n\n## Exercise 7: Turn Export Into A Debug Prompt\n\nWrite:\n\n```markdown\n# Debug Prompt From Agent Marker\n\n## Source Artifact\n\n- marker export:\n- schema version:\n- marker id:\n- marker label:\n\n## Human Explanation\n\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n\n## Nearby Evidence\n\n- console:\n- fetch:\n- error:\n- manual:\n- screenshot:\n- DOM:\n\n## Privacy Boundary\n\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private text removed:\n\n## Task\n\nFind the smallest likely bug path and propose the first verification command.\nDo not invent app state that is not in the marker packet.\n```\n\n## Exercise 8: Design A Bounded Replay Capsule\n\nDo not implement a recorder. Design the packet.\n\n```markdown\n# Bounded Replay Capsule\n\n- schemaVersion:\n- markerId:\n- sessionId:\n- markerCutoffSeq:\n- nearbyEventIds:\n- console:\n- fetch:\n- errors:\n- manual:\n- screenshot:\n- dom:\n- redaction:\n\n## Boundaries\n\n- included:\n- excluded:\n- maximum event count:\n- privacy rules:\n\n## How To Use It\n\n- agent prompt:\n- human review:\n- verification command:\n```\n\nQuestion:\n\n```text\nWhat is the smallest capsule that would let someone debug the marked moment?\n```\n\n## Exercise 9: App-Specific Marker Flow\n\nInspect or design a shortcut flow.\n\n```text\nCtrl+M\n-> create marker id\n-> capture screenshot if available\n-> open note/explanation UI\n-> save human explanation\n-> write durable app logs\n```\n\nPossible inspection command:\n\n```bash\nrg -n \"dev_marker|dev_marker_explanation\" <app-log-path>/latest-session.jsonl\n```\n\nFill out:\n\n```markdown\n# App-Specific Marker Flow\n\n- shortcut:\n- marker id format:\n- screenshot available? yes/no:\n- explanation UI:\n- log path:\n- `dev_marker` written? yes/no:\n- `dev_marker_explanation` written? yes/no:\n- shared marker id? yes/no:\n- what this preserves:\n- what this does not try to solve:\n```\n\n## Exercise 10: Failure Path Drill\n\nFor each failure, choose a recovery.\n\n| Failure | Recovery |\n| --- | --- |\n| marker has no note | |\n| export has thousands of raw log entries | |\n| marker has empty nearbyEventIds | |\n| exported JSON contains sensitive storage values | |\n| console/fetch remains patched after test | |\n| Playwright cannot read `window.__AGENT_MARKERS__` | |\n| marker does not say what to inspect next | |\n| screenshot hook returns nothing | |\n| DOM snapshot includes private text | |\n| smoke test fails before clicking marker buttons | |\n\nRecovery options:\n\n```text\nadd expected/actual note\nfocus on one marker id\nmark closer to the failure\nraise nearbyEventLimit deliberately\nredact and rebuild export\nrestore with stop()\nenable exposeGlobal in dev/test\nwait for app readiness\nadd next action\nmark screenshot unavailable\nnarrow DOM snapshot\nsave failed smoke and retry with sharper condition\n```\n\n## Exercise 11: Section 9 Bridge Packet\n\nUse one marker export to prepare a bounded work unit.\n\n```markdown\n# Section 9 Bridge: Imp Debug Packet\n\n- source artifact: DebugSession export\n- schemaVersion:\n- marker id:\n- marker label:\n- marker note:\n- nearbyEventIds:\n- evidence lanes:\n  - console:\n  - fetch:\n  - error:\n  - manual:\n- privacy checks:\n  - storageHasValues:\n  - request bodies exported? no\n  - response bodies exported? no\n- likely app area:\n- required verification:\n  - npm test\n  - npm run typecheck\n  - npm run build\n- next action:\n```\n\nFill out:\n\n```markdown\n# Bridge Review\n\n- packet names one marker id? yes/no:\n- nearby evidence is bounded? yes/no:\n- privacy rules are explicit? yes/no:\n- verification commands are present? yes/no:\n- task is clear enough for an Imp? yes/no:\n- what would make it smaller or sharper:\n```\n\n## Final Check\n\nInspect manually:\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  schemaVersion: session.schemaVersion,\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),\n  eventTypes: [...new Set(session.events.map((event) => event.type))],\n});\n```\n\nFill out:\n\n```markdown\n# Final Agent Markers Check\n\n- marker created? yes/no:\n- marker has human explanation? yes/no:\n- nearbyEventIds present? yes/no:\n- console evidence captured? yes/no:\n- fetch evidence captured? yes/no:\n- error evidence captured? yes/no:\n- manual evidence captured? yes/no:\n- storage values avoided? yes/no:\n- export saved? yes/no:\n- test runner can export? yes/no:\n- `stop()` cleanup handled? yes/no:\n- next action written? yes/no:\n- ready to hand off as bounded debug packet? yes/no:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
