e2e-walkthrough

name	e2e-walkthrough
description	Use when walking through UI flows interactively with human guidance — visual QA, exploring features, or recording demos. Records video by default. Triggers on "walkthrough", "walk the UI", "visual QA", "demo recording".

E2E Walkthrough — Interactive UI Exploration

Human-agent collaborative browser walkthrough with trace recording, health monitoring, and reusable flow output.

Role

Interactive human-in-the-loop browser exploration. Use this when:

• Exploring unknown features — no spec, discovering what the app does
• Visual QA — subjective design review, layout inspection, responsive check
• Debug escape hatch — automated /e2e-flow --verify failed, need human eyes
• Demo recording — walkthrough with human narration for stakeholders

For automated flow generation → /e2e-flow For automated flow verification → /e2e-flow --verify-only For smoke testing → /e2e-flow --smoke

Pipeline Context

/e2e-map       -> mapping.yaml    (map)
/e2e-walkthrough -> flow.yaml     (explore with human)
/e2e-test      -> report.md       (replay with monitoring)

Invocation

/e2e-walkthrough [context] [--mode guided|step|auto] [--sites name1,name2] [--pr N] [--issue ID] [--no-video]

Entry point	Behavior
--pr 940	Read PR diff, propose path covering changed UI
--issue DRC-2811	Read issue, propose path for the feature
Free text	Use mapping + codebase to propose path
--page org-settings	Explore all mapped elements on that page
--sites admin,portal	Cross-site walkthrough using named mappings
--no-video	Skip screen recording (default: recording ON)

Not a walkthrough flag: --verify, --verify-only, --smoke → redirect to /e2e-flow with appropriate flag. Walkthrough is interactive exploration, not automated verification.

Discover Mapping (BLOCKING — must complete before proceeding)

1. Look for .claude/e2e/mappings/*.yaml
2. One file: use it. Read app, base_url, auth from the mapping.
3. Multiple files: list them (show filename, app, base_url for each), ask user which to use (or accept --mapping <name>). After selection, use ONLY the chosen mapping — do not reference pages/elements from other mapping files.
4. None: "No mapping files found in .claude/e2e/mappings/. Mappings define page structure, selectors, and auth config that walkthroughs depend on. Run /e2e-map to create one first." Stop — do NOT continue to Pre-Flight. "Exploration mode" and "discovery" are NOT reasons to skip mapping — mappings provide base_url, auth config, and page structure that walkthroughs depend on even for open-ended exploration.
5. If mapping YAML fails to parse: report the parse error with line number and stop. "Mapping file <path> has invalid YAML at line N. Fix the syntax error or re-run /e2e-map to regenerate."

Multi-Site Discovery (when --sites provided)

1. Parse --sites argument: comma-separated mapping names (filename without .yaml)
2. Load each mapping from .claude/e2e/mappings/<name>.yaml. If any not found -> report and stop.
3. Assign aliases: use the mapping's app field as the alias
4. Present merged page list:

Available pages:
  [admin-panel] users_page, dashboard, settings
  [customer-portal] projects_page, user_profile, billing

Which page to start? >

Prerequisites & Pre-Flight

After Discover Mapping completes, proceed to Pre-Flight. These checks use base_url and app from the selected mapping.

1. agent-browser installed globally
2. Dev server running (read base_url from mapping)
3. Auth profile (derived from mapping app: ~/.agent-browser/<app>)
4. --headed mode — human must see the browser (NOT headless)

agent-browser --version
curl -s -o /dev/null -w "%{http_code}" <base_url>
ls ~/.agent-browser/<app>/ 2>/dev/null && echo "OK" || echo "MISSING"

If agent-browser is not installed, stop and report: "agent-browser is required for browser automation. Install from https://github.com/nicobrinkkemper/agent-browser." If the dev server is unreachable, stop and report: "Cannot reach <base_url>. The walkthrough navigates real pages so the dev server must be running. Start it and retry." Any 2xx or 3xx HTTP response means the server is running (3xx is normal for auth-protected apps that redirect to login).

After Pre-Flight passes, proceed to Phase 1.

First-Run Auth (if profile missing):

• If auth.type: none in mapping: skip auth entirely. Profile auto-creates on first open.
• Automated OTP path: If mapping has auth.test_accounts with phone numbers AND the project has Supabase config.toml with [auth.sms.test_otp] entries, automate login: navigate to signin path → fill phone number (strip country code if UI has country selector) → submit → fill OTP from config → submit → verify URL. This avoids blocking on human input for local dev environments.
• Manual path: If no test accounts or OTP config available, open browser agent-browser --profile ~/.agent-browser/<app> --headed open <base_url>, read auth.manual_prompt from mapping and relay it to the user (e.g., "Please complete login in the browser"). After user confirms → agent-browser get url and verify using auth.verification.url_not_contains from mapping (url_not_contains performs a substring check on the full URL). If verification fails, re-prompt user. Repeat until verified or user aborts. Profile persists — login is one-time only.

Knowledge Bootstrap (before Phase 1)

Read accumulated patterns to inform walkthrough execution:

Read → ${CLAUDE_PLUGIN_ROOT}/references/learned-patterns.md

Use loaded patterns to:

• Apply known selector strategies during interactive exploration
• Anticipate framework-specific UI behaviors (e.g., Ant Design hidden inputs)
• Recognize anomaly patterns from past walkthroughs

Phase 1 — Plan

1. Read context: PR diff (gh pr diff), issue description (Linear MCP), or human's text
2. Read discovered mapping file
3. Cross-reference: which pages/elements/dialogs are relevant to the context
4. Propose numbered walkthrough steps with concrete actions

For smoke testing, use /e2e-flow --smoke.

For flow verification, use /e2e-flow --verify-only.

After plan is presented, proceed to Phase 2 for human approval.

Based on PR #940:

Proposed walkthrough (8 steps):
1. Navigate to org-settings
2. Click "Add Connection" -> dialog opens
3. Fill form with test data
...

Mode: guided (default). Adjust? Or "go" to start.

Cross-Site Plan

When --sites is provided, the walkthrough plan includes site transitions:

Proposed walkthrough (6 steps):
1. [admin] Navigate to users_page
2. [admin] Click create_user_button
3. [admin] Fill user form
4. [portal] Navigate to /users -> verify user appears
5. [portal] Open user detail -> grant permission
6. [admin] Navigate to /users -> verify permission

Mode: guided. Adjust? Or "go" to start.

Phase 2 — Approve & Configure

Human adjusts the plan via natural conversation:

• "go" -> start execution
• Add/remove/reorder steps -> agent updates plan
• "auto mode" -> switch interaction mode
• "actually walk onboarding instead" -> back to Phase 1
• "pay attention to console errors on submit" -> agent adds focus area

After human says "go" (or equivalent), proceed to Phase 3.

Phase 3 — Execute & Monitor (Observe-and-Continue)

For detailed execution mechanics (startup, multi-site, per-step loop, anomaly observation, step log), see reference.md.

Summary: Open browser with --profile → verify auth (auto-login if needed) → start trace → execute steps → observe anomalies → write step log. Video is generated post-hoc from step screenshots by the media-processor agent.

Per-step loop (observe-and-continue):

1. snapshot -i → find @ref (interactive-only, less noise)
2. Action via @ref
3. wait networkidle → screenshot
4. errors --json → non-empty? record anomaly + notify (don't stop)
5. Visual observation → unexpected UI? record anomaly + notify (don't stop)
6. One-line report: Step N ✓ / Step N ✓ ⚠ <anomaly summary> / Step N ✗ <failure reason>

Key principle: Anomalies are recorded and reported inline, but the walkthrough never pauses for them. Full analysis happens in Phase 4 via trace cross-reference. The only exception is auth expiration (which makes all subsequent steps meaningless).

Interaction modes: Guided (default, show plan + one-line report), Step (wait "go" between steps), Auto (silent, record anomalies).

Step log: At the end of Phase 3, write $REPORT_DIR/step-log.json with step timestamps + anomalies. This feeds the enhanced trace analyzer in Phase 4.

After all steps complete (or human says "stop here"), proceed to Phase 4.

Phase 4 — Output & Learn (STRICT ORDER)

Execute ALL subsections below in order. Do NOT skip to Browser Handoff.

Print this checklist at the start of Phase 4. Update each line as you complete it. Do NOT proceed to Browser Handoff until lines 1-11 are checked.

Phase 4 checklist:
[ ] 1. trace stop → trace.zip saved
[ ] 2. (reserved)
[ ] 3. trace-analyzer dispatched (with step-log.json)
[ ] 4. anomaly review presented (or N/A if zero anomalies AND trace clean)
[ ] 5. report.md written (full artifact with flowchart + step table + health log)
[ ] 6. pr-summary.md written (PR reviewer version with inline screenshots)
[ ] 7. Media agent dispatched → GIF + MP4 + thumbnail (or N/A if no screenshots)
[ ] 8. (merged into item 7)
[ ] 9. flow YAML written to .claude/e2e/flows/
[ ] 10. PR comment posted with pr-summary.md (or N/A if no --pr)
[ ] 11. mapping discrepancy check done
[ ] 12. D1 knowledge capture (learned-patterns.md)
[ ] 13. browser handoff + action menu presented
[ ] 14. pipeline next steps shown

For detailed procedures (trace analysis, anomaly review, report templates, flow YAML rules, mapping self-repair), see reference.md.

Checklist items map to procedure steps below. Items 5-6 are both from procedure step 5 (dual output). Item 12 is D1 knowledge capture. Item 14 maps to Pipeline Next Steps section below.

1. Stop trace: agent-browser trace stop "$REPORT_DIR/trace.zip"

2. Trace analysis (enhanced): Dispatch e2e-trace-analyzer subagent with trace_path + report_dir + step_log_path. Prerequisite: step-log.json must exist in $REPORT_DIR (written at end of Phase 3). If missing, write it now from in-memory step data and verify the file exists. If write fails again, dispatch WITHOUT step_log_path — analyzer degrades gracefully to non-enhanced mode (no cross-reference, but analysis still completes). See reference.md § Trace Analysis.

3. Anomaly review (checklist item 4): If anomalies were observed during Phase 3 (check step-log.json anomalies arrays) OR trace found issues (clean: false), present the cross-reference summary and offer: review details / fix / re-walk / continue. Skip to step 5 ONLY when BOTH conditions are true: zero anomalies in step-log AND trace returns clean: true. Note: clean: true from trace-analyzer means zero API/console/silent-failure — it does NOT account for unmatched visual anomalies. See reference.md § Anomaly Review.

4. Report (dual output, MANDATORY) (checklist items 5+6): Write both $REPORT_DIR/report.md and $REPORT_DIR/pr-summary.md. Health Log now includes step-correlated data from trace analysis. See reference.md § Report for templates.

5. Media post-processing (checklist items 7+8): Dispatch media agent:

   Agent(subagent_type="e2e-pipeline:e2e-media-processor"):
     "Process media:
      report_dir: $REPORT_DIR
      output_name: walkthrough"
   

   Agent returns: gif_path, mp4_path, thumbnail_path. Use in report + PR summary. Replaces manual GIF generation (old item 7) and MP4 conversion (old item 8).

   CLI-only walkthroughs (rare — walkthrough is primarily browser-based): If the walkthrough involved only Execute external / Verify external steps with no browser interaction, use CLI recording mode instead. Record with asciinema rec during Phase 3, then dispatch media processor with cast_path. See cross-boundary-testing.md § Recording CLI-Only Flows.

6. Flow YAML auto-generation (MANDATORY) (checklist item 9): Always auto-generate — never ask. Auto-name: walkthrough-<timestamp>-<first-page>.yaml. Write to .claude/e2e/flows/. Cross-site: use sites: instead of mapping: when --sites was used. Flow write authorization: Write .claude/e2e/.flow-write-authorized (content: current unix timestamp) before writing the flow YAML, then delete it after the write completes.

7. PR/Issue posting (checklist item 10): If --pr provided, ask user to confirm → commit + push screenshots → gh pr comment with pr-summary.md. See reference.md § PR/Issue Posting.

8. Mapping self-repair (checklist item 11): Present discrepancy list, human approves, patch mapping. 3+ stale on same page → recommend /e2e-map --page

9. D1 Knowledge capture (checklist item 12): Evaluate walkthrough findings for skill-level patterns. Read ${CLAUDE_PLUGIN_ROOT}/references/knowledge-capture.md. Scan anomalies, selector discoveries, and framework behaviors for general patterns. Auto-append to ${CLAUDE_PLUGIN_ROOT}/references/learned-patterns.md. Skip if zero anomalies AND no novel selector/framework observations. Notify: "Appended pattern: [title]"

10. Browser handoff (checklist item 13, BLOCKING: report + flow YAML must be written first): Present summary table, then numbered action menu. Do NOT close browser — user may need to inspect final state.

Post-completion menu (always present, numbered):

What's next?

1. Post report to PR (pr-summary.md → gh pr comment)
2. Edit flow YAML (already auto-generated — rename or adjust steps)
3. Generate GIF (step screenshot animation)
4. Generate video recording (full viewport)
5. Generate GIF + video (both)
6. Done (browser stays open)

• Options 3-5 only shown when recording was active
• Option 1 only shown when --pr was provided or user mentioned a PR
• Option 2 is always shown (flow YAML already auto-generated — this option lets user rename/edit)
• Never close browser without explicit user confirmation
• Multiple selections allowed (e.g., "1, 2")

Pipeline Next Steps (MANDATORY — always shown after menu interaction)

After the user completes their menu selection(s) — including selecting "Done" — present context-aware pipeline guidance:

Next steps:
- `/e2e-test <flow-name>` — replay this walkthrough automatically (flow saved)
{if anomalies found}
- `/e2e-map --page <page>` — re-scan pages with stale selectors
{endif}
- `/e2e-walkthrough` — explore other features or pages

Rules:

• Always show /e2e-test replay line (flow YAML is always generated)
• Show /e2e-map line ONLY when mapping discrepancies were found during this walkthrough
• Always show /e2e-walkthrough continue line
• Use the actual generated flow filename in the /e2e-test suggestion
• This block appears BEFORE browser close confirmation — the user needs this info while deciding whether to continue

Common Mistakes

Top 5 (highest frequency):

Mistake	Fix
Stopping walkthrough for anomalies	Observe-and-continue: record anomaly + notify + keep going. Only auth expiration pauses. Full analysis in Phase 4 via trace cross-reference.
Running console --json at any point during walkthrough	Never used in Phase 3 — not once, not "just for this error." Trace.zip captures complete console with better coverage. errors --json is the only per-step check. If user asks to "pay attention to console," use errors --json — that IS the console error check.
Using full snapshot instead of snapshot -i	Per-step loops always use snapshot -i. Full snapshot only for --smoke post-walkthrough selector sweep or when user explicitly requests element discovery.
Skipping step-log.json write	MANDATORY at end of Phase 3. Trace analyzer needs it for step correlation. Without it, cross-reference sections are absent.
Skipping Phase 4 checklist items	Phase 4 has 14 items (items 2 and 8 are reserved/merged — 12 actionable). Print checklist, complete ALL actionable items. "Context pressure" is NOT a valid reason to skip. If context is genuinely critical, finish the current item fully, then ask user: "Context building up — continue remaining N items or pause?" Never silently drop items.

agent-browser gotchas (see also references/commands.md):

Mistake	Fix
Acting without snapshot	snapshot -i before every action — a11y tree is source of truth
CSS selectors for clicks	Use @ref from snapshot. For visibility checks use [role="<r>"][aria-label="<v>"] CSS attribute selector (Cand 2)
has-text() selectors	BROKEN in agent-browser — times out. Use [role="button"][aria-label="..."] CSS attribute selector or find text "..." subcommand
Screenshot relative paths	agent-browser needs absolute paths (sandbox CWD differs)
Forgetting trace stop	Trace data lost if browser closes without stopping
scroll to element	scroll only accepts direction (up/down). Use hover "@ref" to auto-scroll
is visible exit code always 0	Check stdout text "true"/"false", NOT exit code. Don't chain with &&
Large table snapshots consume context	Use targeted is visible checks instead of full snapshot for 10+ row tables
Assuming snapshot shows data-testid	a11y snapshot does NOT expose data-testid/aria-label. Use is visible
--profile silently ignored	Daemon already running without profile. agent-browser close → wait 3s → re-open
Checkpoint steps interact with browser	verify-external steps do NOT touch browser — skip snapshot, skip element resolution
Browser crash mid-walkthrough	Write step-log.json with steps completed so far → proceed to Phase 4 with partial data. Do NOT restart from step 1 — offer user: "Browser lost at step N. Resume from step N, or proceed to Phase 4 with partial results?"