debug-teach

name	debug-teach
version	1.0.0
description	Debug an `imprint teach` run — env vars, CLI flags, log files, tracing, and diagnostic commands. Helps diagnose slow, stuck, or failing teach runs.
triggers	["debug teach","teach debug","teach is stuck","teach failing","teach logs","debug compile","why did teach fail","inspect teach run"]
allowed-tools	["Bash","Read"]

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:

Scenario	Go to
Teach is currently running and looks stuck	Step 2a
Teach finished but tools are broken	Step 2b
Teach errored out	Step 2c
Teach was slow and user wants to know why	Use /imprint-teach-deepdive instead

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

Variable	Effect
IMPRINT_DEBUG=1	Verbose stderr: every HTTP request, cookie/storage snapshots, Chromium stderr, full stack traces
IMPRINT_QUIET=1	Suppress all imprint logs
IMPRINT_REPLAY_DEBUG=1	Write timestamped replay events to /tmp/imprint-replay-debug-<ts>.log

Tracing (OpenTelemetry → Phoenix)

Variable	Effect
IMPRINT_TRACE=1	Enable tracing (aliases: IMPRINT_TRACING=1, OPENINFERENCE_TRACE=1)
PHOENIX_COLLECTOR_ENDPOINT	Phoenix collector URL (auto-enables tracing)
IMPRINT_TRACE_LLM_IO=1	Capture prompt text + LLM responses in spans
IMPRINT_TRACE_TOOL_IO=1	Capture tool arguments + results in spans
IMPRINT_TRACE_IO=1	Shorthand for both LLM + tool I/O
IMPRINT_TRACE_BATCH=0	Flush spans immediately (useful for short/killed runs)
IMPRINT_TRACE_PROJECT	Phoenix project name (default: imprint)

Compile & planning knobs

Variable	Effect
IMPRINT_KEEP_TEST=1	Keep generated parser.test.ts after compile
IMPRINT_NO_BUILD_PLAN=1	Skip shared-module planning
IMPRINT_NO_TOOL_PLAN=1	Skip per-tool implementation planning
IMPRINT_NO_PREREQ_PLAN=1	Skip prerequisite analysis
IMPRINT_COMPILE_ACT_SPACING_MS=0	Fast compile-time replay (default 25000ms)

Files written during teach

Path	Contents
~/.imprint/<site>/.build-plan-log.json	Incremental planner diagnostics; exists even if planning times out or returns invalid JSON
~/.imprint/<site>/<tool>/.compile-log.json	Full compile-agent conversation
~/.imprint/<site>/<tool>/.tool-plan.md	LLM-generated implementation plan
~/.imprint/<site>/.audit-report.json	Audit results (after imprint audit)
~/.imprint/<site>/.audit-transcript.txt	Audit session transcript
/tmp/imprint-replay-debug-<ts>.log	Replay debug log (IMPRINT_REPLAY_DEBUG=1)
/tmp/imprint-playbook-<tool>-step<N>-<ts>.png	Step screenshots (--trace)

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

Command	Purpose
imprint doctor	Check environment (Bun, Chromium, LLM providers)
imprint check <session>	Validate captured session completeness
imprint playbook <site> --headed --trace	Interactive playbook test with screenshots
imprint audit <site> --json	Score tools; generate report + transcript
imprint mcp status	Audit MCP registrations + generated tools
imprint probe-backends <site>	Test backend ladder