Skip to content

ashaychangwani/imprint / .agents/skills/debug-teach

debug-teach

Verified

Debug an `imprint teach` run — env vars, CLI flags, log files, tracing, and diagnostic commands. Helps diagnose slow, stuck, or failing teach runs.

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:

ScenarioGo to
Teach is currently running and looks stuckStep 2a
Teach finished but tools are brokenStep 2b
Teach errored outStep 2c
Teach was slow and user wants to know whyUse /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

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

Tracing (OpenTelemetry → Phoenix)

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

Compile & planning knobs

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

Files written during teach

PathContents
~/.imprint/<site>/.build-plan-log.jsonIncremental planner diagnostics; exists even if planning times out or returns invalid JSON
~/.imprint/<site>/<tool>/.compile-log.jsonFull compile-agent conversation
~/.imprint/<site>/<tool>/.tool-plan.mdLLM-generated implementation plan
~/.imprint/<site>/.audit-report.jsonAudit results (after imprint audit)
~/.imprint/<site>/.audit-transcript.txtAudit session transcript
/tmp/imprint-replay-debug-<ts>.logReplay debug log (IMPRINT_REPLAY_DEBUG=1)
/tmp/imprint-playbook-<tool>-step<N>-<ts>.pngStep 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

CommandPurpose
imprint doctorCheck environment (Bun, Chromium, LLM providers)
imprint check <session>Validate captured session completeness
imprint playbook <site> --headed --traceInteractive playbook test with screenshots
imprint audit <site> --jsonScore tools; generate report + transcript
imprint mcp statusAudit MCP registrations + generated tools
imprint probe-backends <site>Test backend ladder
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall