---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-marker-workflows-practice"
title: "Agent Markers debugging workflows: practice drills"
---

# Agent Markers debugging workflows: practice drills

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.

```markdown
# Marker Moment

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

Good marker:

```json
{
  "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:

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

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

Fill out:

```markdown
# 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:

```js
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:

```markdown
# Marker Export

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

## Exercise 4: Privacy Review

Inspect the export.

```js
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:

```markdown
# 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:

```ts
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:

```markdown
# 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:

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

Fill out:

```markdown
# 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:

```markdown
# 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.

```markdown
# 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:

```text
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.

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

Possible inspection command:

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

Fill out:

```markdown
# 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:

```text
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.

```markdown
# 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:

```markdown
# 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:

```js
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:

```markdown
# 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:
```

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
