Debug an imprint teach run

Use this when a teach run failed, is stuck, was slow, or produced broken tools.

Step 1 — Determine what happened

Ask the user (or infer from context) which scenario applies:

Step 2a — Stuck teach (still running)

Check what stage it's in:

# See if the compile-log is being written (growing = still compiling)
ls -la ~/.imprint/<site>/*/.compile-log.json

# Check if Chrome is still alive (replay/record stage)
pgrep -fl chromium || pgrep -fl chrome

# If tracing was on, check the last span
bun run scripts/analyze-phoenix.ts --kind teach --last 1

Common stuck points:

• Replay stage: browser hung waiting for a network response. Kill and re-run; check IMPRINT_REPLAY_DEBUG=1 output at /tmp/imprint-replay-debug-*.log
• Compile agent looping: the agent is retrying a failing verification. Check the tail of .compile-log.json
• Shared module build: a module failed to verify and is retrying. Look for pruning vs built + verified in stderr

Step 2b — Teach finished but tools are broken

# Run audit to get a structured report
bun run src/cli.ts audit <site> --json

# Read the audit report
cat ~/.imprint/<site>/.audit-report.json | jq '{score, verdicts: [.verdicts[] | {tool: .tool, verdict: .verdict}]}'

# Read the compile agent's full conversation for a broken tool
cat ~/.imprint/<site>/<broken-tool>/.compile-log.json | jq '.[].role' | head -20

# Check the tool plan the agent was given
cat ~/.imprint/<site>/<broken-tool>/.tool-plan.md

# Test the playbook interactively
bun run src/cli.ts playbook <site> --headed --trace --param key=value
# Screenshots land at /tmp/imprint-playbook-<tool>-step<N>-<ts>.png

Step 2c — Teach errored out

# Check the compile log for the error
cat ~/.imprint/<site>/<tool>/.compile-log.json | jq 'last'

# Validate the session recording is intact
bun run src/cli.ts check ~/.imprint/<site>/sessions/*.json

# Check environment
bun run src/cli.ts doctor

Environment variables reference

Verbosity & logging

Tracing (OpenTelemetry → Phoenix)

Compile & planning knobs

Files written during teach

Quick recipes

# Full-verbose teach
IMPRINT_DEBUG=1 IMPRINT_REPLAY_DEBUG=1 imprint teach <site> --url <url> 2>&1 | tee teach-run.log

# Teach with Phoenix tracing
IMPRINT_TRACE=1 IMPRINT_TRACE_LLM_IO=1 imprint teach <site> --url <url>

# Fast iteration (skip slow parts, reuse existing session)
IMPRINT_COMPILE_ACT_SPACING_MS=0 IMPRINT_NO_PREREQ_PLAN=1 \
  imprint teach <site> --skip-replay --from-session <path>

# Capture everything to a file
IMPRINT_DEBUG=1 imprint teach <site> --url <url> 2>&1 | tee teach-$(date +%s).log

Diagnostic subcommands