e2e-debug

E2E Debug: trace analysis + healer (close the loop)

The third leg of the harness. A CI failure is a sensor reading; this skill turns it back into a green test (or an honest quarantine), closing the planner -> generator -> healer self-improving loop.

Two runtime families, three execution paths, same bounded loop: on Claude Code the healer is the named agent playwright-test-healer that e2e-setup generated (Path A); on Codex that agent file is not registerable, so the healer runs as a generic subagent carrying the bundled contract from references/role-contracts.md (Path B), or in-agent sequentially when no delegation is available (Path C).

The headless npx playwright trace CLI exists only in newer Playwright releases; probe for it (Precondition check) instead of trusting a version number. On Path A, npx playwright trace install-skill installs Playwright's own agent skill for it (it writes to .claude/skills/ only, so it does nothing for Codex). The GUI viewer npx playwright show-trace <trace.zip> is also available if a human wants to look.

Precondition check

• Need gh CLI authenticated to fetch CI artifacts.
• Path A only: confirm the named healer exists (.claude/agents/playwright-test-healer.md). If missing and you are on Claude Code, route to dev:e2e-setup. Do not demand this Claude agent file under Codex; there the bundled healer contract stands in (see Step 0).
• Probe the headless trace CLI used in Step 2: run npx playwright trace --help and check that it printed the trace subcommand's own usage, not the top-level help (an unknown subcommand can answer with the top-level help and exit 0). When it is missing: fall back to the GUI viewer npx playwright show-trace <trace.zip>.

Workflow

1. Resolve the plugin root + pick the execution path: run once. The resolver reaches the bundled healer contract on Path B/C; the path decision governs Step 3. Tell the user which path you took in one sentence.

   # Claude exports CLAUDE_PLUGIN_ROOT; Codex does not. Each branch verifies
   # the target (CHK) exists before committing, so a stale env falls through.
   CHK="references/role-contracts.md"
   PLUGIN_ROOT=""
   [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -e "$CLAUDE_PLUGIN_ROOT/$CHK" ] && PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"
   [ -z "$PLUGIN_ROOT" ] && [ -e "plugins/dev/$CHK" ] && PLUGIN_ROOT="plugins/dev"
   if [ -z "$PLUGIN_ROOT" ]; then
     cache_root="${CODEX_PLUGIN_CACHE:-$HOME/.codex/plugins/cache}"
     while IFS= read -r d; do
       [ -e "$d/$CHK" ] && { PLUGIN_ROOT="$d"; break; }
     done < <(ls -1d "$cache_root"/*/dev/*/ 2>/dev/null | awk -F/ '{print $(NF-1)"\t"$(0)}' | sort -t. -k1,1rn -k2,2rn -k3,3rn | cut -f2- | sed 's#/$##')
   fi
   { [ -n "$PLUGIN_ROOT" ] && [ -e "$PLUGIN_ROOT/$CHK" ]; } || { echo "e2e-debug: role contracts not resolved (need $CHK)" >&2; exit 1; }
   echo "PLUGIN_ROOT=$PLUGIN_ROOT"
   

   • Path A: named playwright-test-healer is registered (Claude Code). Dispatch it by name (Step 3, unchanged).
   • Path B: named agent not registerable but a generic subagent tool is available (Agent). Dispatch a generic subagent carrying the healer contract from ${PLUGIN_ROOT}/references/role-contracts.md inline.
   • Path C: no delegation available. Run the healer role yourself per the same contract.