@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.10

package/dist/templates/skills/iamu-run.md

@@ -0,0 +1,520 @@
+---
+name: iamu-run
+description: Execute a scenario walkthrough. Accepts scenario slug / UUID / free-form intent / no-arg. Intent chains into iamu-new first, then runs.
+generatedBy: __IAMU_VERSION__
+---
+
+Run a scenario against a running product. The walkthrough executes in your agent session using a driving surface you control — a browser MCP for a web product, or the iOS Simulator for a native app — no separate Iamu runner involved for local flows.
+
+This skill resolves what you want to run from your argument:
+
+- Scenario slug or UUID → load + execute.
+- Free-form intent ("checkout abandonment", "returning customer friction") → fuzzy-match against existing scenarios; if nothing fits, chain into `iamu-new` to draft first, then execute.
+- No argument → pickable list of scenarios: scenarios that need a re-run first, then drafts and ready-to-run.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` exists and has `domain` filled in. If it is missing or empty, run the `iamu-setup` skill first — context grounds every walkthrough. If `iamu/` does not exist at all, run `iamu init` first.
+
+## Steps
+
+### 0. Verify a driving surface
+
+A walkthrough needs something that drives the product the way a person does. Two surfaces are supported — pick the one the product actually IS, not the one that is easiest to reach.
+
+Look at the tools actually available in this session and match on what they can do, not on what they are called — tool names differ per host, plugin, and install method, so any name written here would be wrong somewhere.
+
+**Web product** — you need a browser-driving tool set that can: open a URL, click and type into elements, read the page structure (accessibility snapshot or DOM), and save a screenshot to a file path on disk.
+
+When more than one qualifies, prefer in this order:
+
+1. **One attached to the user's own running Chrome** (a Chrome DevTools-style MCP or a Chrome extension bridge). The user can watch the walk live, the session and dev state they already have is present, and console and network output are available to tell a tooling glitch from a product bug.
+2. **One that launches its own browser** (a Playwright-style MCP). Works, but starts from a blank profile and the user cannot see it happen.
+3. **`iamu browse`** — the CLI's own shell-driven browser, when no tool above can save a screenshot to a file (many hosts' browser tools return screenshots to the model only, and every step then records `screenshot: null`). It drives the installed Chrome in a visible window: `iamu browse start --run <run-id>` after each `start-run` (step 4), then `goto`, `snapshot` (ARIA roles and names), `click <role> "<name>"`, `click-text`, `fill <role> "<name>" "<text>" [--submit]`, `press`, `scroll`, `back`, each with `--shot <png>`; `iamu browse stop` when done. Start it yourself before dispatching the walker, never leave that to the walker; `iamu instructions walk --surface browse` (the default) writes the command list into the walker prompt.
+
+Tell the user in one line which one you picked and why. If the project's own agent docs name a preferred browser tool or constrain where screenshots may be written, that wins over the order above.
+
+**Native iOS / iPadOS app** — you need a simulator control tool that can tap, type, and launch an app on a named device.
+
+A native app has no URL, and a browser tool is not a substitute for one. If the product is native, the target is a device plus a build (step 3).
+
+If no surface is available, stop and tell the user:
+
+> A walkthrough needs a driving surface. For a web product, `iamu browse` works wherever Chrome or Chromium is installed (or set `IAMU_BROWSER`); a browser-driving MCP that attaches to Chrome also works — restart your agent session after installing one and re-run `iamu-run`. For a native iOS app, a simulator control tool must be available in this session.
+
+Do NOT proceed to step 1 before a driving surface is confirmed.
+
+**Unfinished runs.** Only check and offer when `iamu-run` is invoked without arguments (`$ARGUMENTS` is empty). If an explicit scenario slug or intent was passed, do NOT block execution with this prompt — log a single line (`Note: <N> unfinished run(s) pending — use iamu status to inspect`) and proceed directly to step 1.
+
+When `$ARGUMENTS` is empty, check `iamu status --json` for `runs.incomplete`. If any exist, offer once:
+
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Found <N> unfinished walkthrough run(s). How would you like to handle them?"
+  - Options:
+    1. "[Recommended] Ignore and continue with new run"
+    2. "Finish run `<run-id>`: Run post-walk assembly on existing steps"
+    3. "Discard empty unfinished runs"
+- Otherwise (in CLI or text-only environments), present as an enumerated list (1, 2, 3) and carry on if the user selects 1 or skips:
+  1. [Recommended] Ignore and continue with new run
+  2. Finish run `<run-id>`: Run post-walk report assembly on existing step files
+  3. Discard empty runs with no steps
+
+Press Enter to continue [1], or select 2-3:
+(Treat empty Enter as Option 1)
+
+Do not block the new run on this, and do not ask again in the same session.
+
+**Cloud state.** Run `iamu auth status --json` once. It sets the mode for the rest of this skill:
+
+- **Linked** (`cloud_linked` and `authenticated` both true) → pull teammates' changes before resolving the scenario: `iamu pull --json`. Pull only adds new entities and fast-forwards files that are unedited here; it never overwrites a local edit (those come back as `diverged` — mention them, never `--force`). This is how a teammate's new scenario, or a dismissal that taught the walker what not to report, reaches this run. If pull fails (offline, cloud down), say so in one line and walk locally.
+- **Linked, no credentials** (`cloud_linked` true, `authenticated` false) → say once: "This project is cloud-linked, but this machine has no credentials — the run stays local until `iamu auth login`." Continue.
+- **Local-only** → nothing to do here.
+
+### 1. Resolve the argument
+
+Four paths based on `$ARGUMENTS`:
+
+**UUID or exact slug match** → Read scenario files from `iamu/scenarios/` directory, or run `iamu list scenarios --json`, and match. Load and skip to step 3.
+
+**Slug-like arg with no exact match** → Run fuzzy match against existing scenario slugs (simple substring / levenshtein — the agent should judge similarity). If the best match is obviously close (shared two or more tokens), confirm with the user: "Did you mean `<slug>`?" Accept / correct / treat as free-form intent.
+
+**Free-form intent string** (quoted or multi-word, no match) → Chain into `iamu-new` with the intent as seed. After `iamu-new` completes and returns a scenario slug, continue here with that slug.
+
+**No arg** → Run `iamu status --json` and `iamu list scenarios --json` (or read `iamu/scenarios/`). `rerun` in the status output lists scenarios holding fixes that no later run has proven yet — a fix counts only once a re-run of its scenario shows it working. Present that group first, most awaiting fixes first, with its `reason`; then drafts and ready-to-run (a scenario in the first group is not repeated below):
+
+```
+Needs a re-run (fixes awaiting proof):
+  1. maria-gomez--busy-shift — 2 fixes applied after the last run
+
+Drafts (need persona):
+  2. busy-shift-draft — Busy shift situation (no persona)
+  3. checkout-abandon-draft — Abandoned cart situation (no persona)
+
+Ready to run:
+  4. dev-patel--checkout-abandon — Abandoned cart x Dev Patel
+```
+
+Omit the first group when `rerun` is empty. If `requests.open` in the status output is above zero, put one line above the list: `Team requests: <N> waiting — iamu-findings picks them up.` Teammates queued those in Iamu Cloud; a verify or run request names the scenario to walk.
+
+**Interactive Scenario Selection:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it with the top prioritized candidates as selectable options:
+  - Question: "Which scenario would you like to run?"
+  - Options:
+    1. "[Recommended] <Slug or Title>" (e.g. top rerun needing proof, or primary ready scenario)
+    2. "<Alternative Scenario Slug or Title>"
+    3. "Draft a new scenario..."
+- Otherwise, prompt: "Pick a scenario number (1–N), enter a slug, or type an intent to draft a new one."
+
+Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
+
+### 2. Bind persona (draft path only)
+
+If the resolved scenario has `persona: null`, prompt to bind before executing:
+
+**Interactive Persona Binding:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "This scenario is a draft with no persona bound. Which persona should walk it?"
+  - Options:
+    1. "[Recommended] <Existing Persona 1> (<Role>)"
+    2. "<Existing Persona 2> (<Role>)"
+    3. "Draft a new persona candidate"
+- Otherwise, ask: "This scenario is a draft — no persona bound. Pick an existing persona (1–N), or type 'new' to propose candidates."
+
+1. Read `iamu/personas/` directory or run `iamu list personas`; present as pickable list + "new" option.
+2. Picked existing → bind that persona by updating the scenario file's `persona` field.
+3. Picked "new" → generate 3 persona candidates grounded in the situation narrative and project context → user picks one + refines → write persona file to `iamu/personas/<slug>.md` → bind.
+4. After binding the persona, generate a 3--5 sentence first-person brief and write it as the scenario file's markdown body:
+
+   ```yaml
+   ---
+   id: <uuid>
+   slug: maria-gomez--busy-shift-handoff
+   outline: busy-shift-handoff
+   persona: maria-gomez
+   ---
+   I've got five open incidents and my relief is already here...
+   ```
+
+After bind + brief, the scenario is ready to execute. Continue to step 3.
+
+### 3. Target
+
+**Web** — determine the target URL:
+1. If the user passed an explicit target or the scenario has `target_url`, use that.
+2. Otherwise, check `iamu/testability.md` for `target_url`.
+3. If still unconfigured, prompt the user for the target URL (live product, staging, or localhost).
+Verify target reachability and dev server health with `iamu doctor --target <url>` before launching. If `localhost` is unreachable, prompt the user to boot their dev server (e.g. `npm run dev`) or ask before launching it, so the walker does not fail against an unstarted port.
+
+Where the walk *starts* is part of the situation, not of the environment: a persona arriving from a video, an email or a search result lands on a specific page, not the home page. If the scenario has `entry_path`, `iamu start-run` resolves it against the target — pass the product's base URL as `--target`. If it has none but the situation clearly begins on a particular page, set `entry_path` in the scenario frontmatter first (a path like `/en/episodes/1`, never a full URL), so this run and every later one start there. A walk started on the wrong page reports the detour as a finding.
+
+**Native iOS** — the target is a device plus a build. Establish three things:
+
+- **Which simulator.** Use a DEDICATED device, never the one the project builds to. An `xcrun simctl install` from any other session terminates the app and relaunches it WITHOUT its launch arguments — so a seeded state silently becomes first-run onboarding, mid-scenario. The walker records that as a product defect, and she is right to: nothing visible to her distinguishes it from the product breaking.
+- **Which build.** An installed bundle id, or a freshly built `.app` to install first. Never walk a build that is still being edited — findings from a half-finished screen cannot be attributed to any commit.
+- **Launch arguments**, if the scenario needs a particular state or entry point.
+
+Record it as a target string the run can carry, for example `sim://<device-name>/<bundle-id>`.
+
+**Then verify the starting state before spawning anyone.** Launch the app and take ONE screenshot confirming the product is where the scenario assumes it starts. Wait a few seconds after launch first: a screen rendered before its state lands shows the wrong thing, and verifying too early makes the verification itself lie — in the direction of "the harness is broken", which costs a debugging detour or, worse, waves a real seeding bug through.
+
+**Expected State & Semantic Squinting — verify environment before walking.** A scenario testing triage, review, or audits requires a populated, realistic system.
+1. **Expected State:** If the scenario defines `state.description`, verify the landing screen matches what the persona expects to see (e.g. populated register, open incidents). If the screen is completely blank and the persona cannot self-seed, stop early and report the run as blocked by missing preconditions rather than logging false product bugs.
+2. **Data Squinting & Approximation:** If the exact record described in the narrative is absent (e.g. no "damaged conveyor belt" hazard), the walker must follow `state.approximation` — "squint" at the real data, pick the closest plausible record (e.g. an active mechanical or safety hazard), and proceed with the evaluation/delegation workflow.
+   - **Squinting Guardrail:** Squinting is bounded to semantically related items within the same domain workflow. It does NOT permit drifting to unrelated modules (e.g. switching from risk assessment to user profile settings). If no plausible record exists, declare the run blocked.
+3. **Empty State Fallback:**
+   - If the database is empty and the persona role has creation rights (e.g. Manager or Reporter), the persona may create the minimal viable record in-character to proceed with the core test.
+   - If the persona role is read-only or subordinate (cannot self-seed), stop and report the run as blocked by preconditions.
+
+**Access — how the walker becomes this persona.** A walk as a forklift driver that runs with an administrator's session reports nothing true about what the driver can see or reach. Access is recorded in two places, and `iamu instructions walk` (step 4) returns both as `access`:
+
+- `access.project` — from `iamu/context.yml` `access`: HOW switching user is done in this product (a dev persona switcher, a storage key, seeded test accounts, a login form). Written once per project.
+- `access.persona` — from the persona file's `access`: WHICH user this persona is (an account name, a role, a switcher key).
+
+**Interactive Auth Handshake (for enterprise auth, SSO, 2FA, BankID):**
+If the product is behind enterprise login where automated dev persona switching is not configured:
+1. Open the browser to the target URL (`iamu browse start --run <run-id>` or browser tool).
+2. Prompt the human user:
+   > 👉 **Please log in as `<persona.role>` (`<persona.name>`) in the opened browser window.** Press Enter once you reach the dashboard to hand control to the walker...
+3. Wait for the user to confirm, then let the walker drive the authenticated session.
+
+If automated switching exists:
+1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`) for a documented way to switch user or role.
+2. Map the persona to the closest account or role the product actually has. If nothing fits, say so.
+3. Write what you learned: the mechanism into `iamu/context.yml` as `access:`, the persona's own key into `iamu/personas/<slug>.md` frontmatter as `access:`. Passwords and tokens never go in either — name where they live (an env var, a vault entry) instead.
+
+Carry the result into the walking prompt as the `## Access` section: the exact steps to become the persona, with the instruction to do them BEFORE the first recorded step.
+
+### 4. Execute the walkthrough
+
+**Set up the run directory.** Use the CLI to scaffold a valid run:
+
+```bash
+iamu start-run <scenario-slug> --target <target> --json
+```
+
+This creates the run directory, writes `walkthrough.json` with resolved persona/outline slugs and the build under test (git SHA and branch, whether there are uncommitted changes outside `iamu/` with a fingerprint of them, CI run when in CI), and returns:
+```json
+{ "run_id": "...", "path": "...", "scenario_slug": "...", "target_url": "...", "persona_slug": "...", "outline_slug": "...", "build": { "git_sha": "...", "git_branch": "...", "git_dirty": false }, "environment": "https://staging.example.com" }
+```
+
+Pass `--build <label>` to name the build (a version or release tag) and `--env <name>` to name the environment (`staging`, `production`); without `--env` the environment is the target URL's origin. Neither is needed for a local walk.
+
+Use the returned `run_id` and `path` for all subsequent operations.
+
+**Size the browser for this persona** (`iamu browse` only), every run — also when a browser is already open from an earlier run:
+
+```bash
+iamu browse start --run <run-id>
+```
+
+It sizes the page as the device the persona's tags name (`mobile`/`phone`, `tablet`/`ipad`, `desktop`/`laptop`; `start-run` prints it as `device`) and resizes a browser left at another persona's size.
+
+**Get the walker prompt.** The CLI composes the whole thing — persona, situation, brief, access, driving surface, methodology, dismissed findings and the run-directory contract (steps, screenshots, findings, `summary.json`):
+
+```bash
+iamu instructions walk --scenario <scenario-slug> --run <run-id> --surface browse --json
+```
+
+`--surface browse` (the default) describes `iamu browse`; start it first (`iamu browse start --run <run-id>`, above). Using your own browser tool instead, pass one sentence naming it and how it saves screenshots, e.g. `--surface "Chrome DevTools MCP attached to the user's Chrome; take_screenshot with filePath"`. For a native app, describe the simulator tool and add the native notes below.
+
+The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim — do not rewrite, summarize or trim it. The prompt already carries the dismissed findings, the active tester guidance rules (`iamu/guidance/`) for this scenario, and — when fixes await a re-run — the places they were seen (places only, never what was wrong; the list is in `revisit`). The rest of the bundle (`persona`, `outline`, `access`, `dismissed_findings`, `tester_guidance`, …) is there for you, not the walker. If `access` is missing a half, fill it in first (step 3) and re-run this command.
+
+**Preflight: Unattended execution check.** A walkthrough executes 15–30 terminal commands sequentially (`iamu browse step`, `iamu new-finding`). If your agent host requires manual confirmation for terminal/shell commands (standard interactive mode in Claude Code, Cursor, Antigravity, Cline, Windsurf, etc.), the walker subagent will stall waiting for approval on every step. Before dispatching, verify that command auto-approval / unattended execution is enabled in your environment, or warn the user once:
+> "Autonomous walkthroughs require auto-approving terminal commands so the walker can drive the product unattended. If command approvals are prompted, please enable auto-approval or expect to approve steps manually."
+
+**CRITICAL: Dispatch the walker as an isolated subagent.** Spawn a fresh subagent using your host editor's subagent mechanism (e.g. `Agent(...)` in Claude Code, `invoke_subagent` in Antigravity, or host-native subagent launcher). The subagent gets ONLY the walking prompt (`walker_prompt`) — no prior conversation history.
+
+A fresh subagent is NOT blind by default. On most hosts it still loads the project's agent instructions and can read files in the repo, so it may know the domain model, the route table, and why a screen was built the way it was — none of which the persona knows. The methodology's "Stay outside the product" rule is what keeps it honest; it is part of `walker_prompt` — never remove or soften it. If the host lets you restrict a subagent's tools, give the walker only the driving surface, file write/edit, and a shell for `iamu` commands.
+
+**Model tiering & subagent dispatch:**
+- **Walker (Browser Navigation):** High turn count, mechanical tool-use. Use the **fast** model tier (`flash` or `haiku`) by default to cut walk time by ~60% and conserve session quota.
+- **Matcher & Judge:** Broad synthesis and semantic comparison. Use the **thorough** frontier tier (`pro`, `sonnet`, or active model) to prevent severity inflation.
+
+```
+# In Claude Code:
+Agent({ description: "Walk <scenario-slug> as <persona.name>", model: "haiku", prompt: "<walker_prompt, verbatim>" })
+
+# In Antigravity / generic subagent hosts:
+invoke_subagent(Role="Persona Walker", Model="flash", Prompt="<walker_prompt, verbatim>")
+```
+
+The subagent inherits the driving-surface tools and drives the product independently. It does not see this conversation.
+
+**For a native walkthrough, append these to `walker_prompt`** (the one addition allowed), or the run produces instrument artefacts instead of findings:
+
+- **She is deaf.** The simulator returns no audio. She may report "I tapped the speaker and nothing visibly confirmed it played" — never anything about what the audio said.
+- **Taps miss.** She taps a coordinate read from a screenshot taken BEFORE the action; mid-animation it lands nowhere. One no-change is never a finding — retry once at the same target, and only a second no-change becomes one.
+- **Screenshot every 3-4 taps at most.** Batching more desyncs the moment an answer opens a screen she did not expect.
+- **Coordinates are device points, origin top-left.** A scaled screenshot must be mapped back to that space before tapping.
+
+**If subagent dispatch or model-switching is not supported by your host editor** (e.g. standard Cursor / Windsurf single-session mode), fall back to walking directly in the current session (inheriting the active model) — but strictly adhere to the persona behavioral constraints in `walker_prompt`.
+
+After the walker returns, continue to the post-walk pipeline below.
+
+**Recording steps:**
+
+Use atomic CLI commands to drive and record in one step — do NOT manually author JSON files:
+
+- **When using `iamu browse` (web):**
+  ```bash
+  iamu browse step --run <run-id> --action "Opened dashboard" --note "First thing I see is the overview panel" goto https://app.example.com/dashboard
+  iamu browse step --run <run-id> --action "Click checkout" --note "Button was hard to find" click button "Checkout"
+  ```
+  **Avoid shell quoting friction:** When persona notes or actions contain quotes, apostrophes, or multi-line monologues, use `--step-file <path>` (or `-` for stdin) to avoid shell escaping errors:
+  ```bash
+  iamu browse step --run <run-id> --step-file <path-to-step.json> click button "Checkout"
+  # or pass the entire action payload including cmd via JSON / stdin:
+  # { "action": "...", "note": "...", "cmd": ["click", "button", "Checkout"] }
+  ```
+  This executes the browser action, waits for the DOM, takes the screenshot into `screenshots/step-N.png`, captures the URL, and writes `steps/NNN.json` atomically.
+
+- **When using an external surface (iOS Simulator / custom MCP):**
+  ```bash
+  iamu step --run <run-id> --action "Tapped proceed" --note "Next screen loaded" --shot <screenshot-path>
+  ```
+
+Step files live at `iamu/.runs/<run-id>/steps/<NNN>.json`. The CLI manages monotonic step numbers, timestamps, and screenshots. Never write raw JSON files with glue code.
+
+**Recording findings:**
+
+Use the CLI to create findings with valid frontmatter, UUID, and slug:
+
+```bash
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --json
+```
+
+This generates a valid UUID, derives the slug from the title, and writes a frontmatter-valid file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`.
+
+After the CLI scaffolds the file, edit the file to add the finding body (description + recommendation) below the frontmatter.
+
+Valid `--type` values: `helps`, `hinders`, `missing`, `irrelevant`, `incorrect`.
+Valid `--severity` values: `critical`, `major`, `minor`, `observation`.
+Valid `--task-impact` values (effect on the persona's task): `blocks`, `impairs`, `slows`, `neutral`, `accelerates`, `enables`. A `helps` finding is never `blocks`/`impairs`/`slows`; a problem is never `accelerates`/`enables`.
+Valid `--confidence` values: `high`, `medium`, `low` (use `low` when it may be a tooling limitation).
+
+Findings never name a human test: the walker does not see them. The judge links findings to the human tests they bear on (`evaluate-record` writes `human_test_id`).
+
+**DEPTH GATE:** Both `--ui-fact` and `--consequence` should be provided. If you cannot articulate both, record as a step note instead — do not create a finding file.
+
+**Post-walk pipeline (MANDATORY — do NOT skip any step):**
+
+After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order.
+
+**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
+
+```bash
+iamu complete <run-id> --no-prompt --no-push --json
+```
+
+This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, and computes the delta against prior runs.
+
+**B. Match findings to earlier runs.** Get the matcher bundle:
+
+```bash
+iamu match <run-id> --json
+```
+
+If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to accurately evaluate semantic equivalence). Write its JSON answer to `<matches.json>` and record it:
+
+```bash
+iamu match-record <run-id> --file <matches.json>
+```
+
+This links recurrences to their earlier canonical finding, marks earlier findings the run's steps show fixed (only with cited steps), and re-derives the delta and report. If the matcher's output is rejected, show the error to the matcher once and retry; if it fails again, continue without it — the exact-text delta from A stands.
+
+**C. Evaluate human tests.** Get the evaluation prompt:
+
+```bash
+iamu evaluate <run-id> --json
+```
+
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt (use the **thorough** model tier, e.g. `Model="pro"` in Antigravity, to prevent severity inflation). After the evaluator returns verdicts, record them locally with `--no-push`:
+
+```bash
+iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
+```
+
+This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
+
+**D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including verification delta (if a prior run exists). Use this for step 5 presentation.
+
+**E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
+
+```bash
+iamu sync --json
+```
+
+Then get the run's link:
+
+```bash
+iamu open <run-id> --print
+```
+
+It prints the URL only if the run is on the cloud; otherwise it exits 1 and says why. Keep the URL — or the reason — for step 5. From the sync result, keep `conflicts` (a teammate changed the same finding) and `pending_deletes` for step 5 too. Never run `iamu sync --keep-mine` or `--confirm-deletes` yourself: both overwrite or delete team data, and only the user decides that.
+
+In linked-no-credentials or local-only mode, skip E.
+
+Only after A→E are complete, proceed to step 5.
+
+### 4a. Walk methodology summary
+
+The `walker_prompt` from `iamu instructions walk` is the source of truth and contains full walking methodology for the subagent.
+
+- **Depth gate**: Ensure findings articulate both the specific UI fact and the consequence for this persona.
+- **Dedup**: Skip findings in the dismissed list or already logged in the current run.
+- **Graceful degradation**: On judge evaluation failure, set verdicts to pending/null and proceed with report presentation.
+
+### 5. Present assessment — stay in the conversation
+
+Render results **inline** with a high-contrast executive summary banner, followed by findings enriched with persona voice, evidence citations, and clickable file links.
+
+1. **Executive Summary Banner & Focus Checkpoint**
+
+   Read the outline's `human_tests[0].question` and answer it directly. Use the evaluation verdict if available:
+
+   ```
+   Walkthrough: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
+   Verdict: <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (Steps: <N>)
+   Focus Checkpoint: "<human_tests[0].question>" → <No / Partial / Yes>: <1-2 sentence direct answer explaining why>
+   ```
+
+2. **Progress since last run** (only when canonical.json contains a `verification` section). Present the delta:
+
+   ```
+   Since this scenario's last run:
+     ✓ 1 fixed, re-checked (handoff note saves — step 6)
+     ✗ 1 persists (timeout warning)
+     ○ 2 not seen this run (handoff list filtering, submit confirmation)
+     + 1 new since that run (date picker locale)
+   ```
+
+   `resolved` means the matcher saw this run's steps do the thing the finding said failed — say which step. `not_observed` means only that this walk did not record the finding again. Never present it as fixed: the walker may have stopped before that screen or taken another route. Say which ones were not seen and, if the walk plainly never reached the screen they live on, say that too.
+
+3. **Findings** — severity-first (CRITICAL → MAJOR → MINOR), grouped by type (hinders and missing first, helps at the bottom). For each finding, include the **persona reaction**, **evidence citation**, and **clickable link**:
+
+   **Hinders / Missing** (act on these):
+
+   1. [CRITICAL · hinders] Submit fails opaquely when required field empty ([file](iamu/findings/<slug>.md))
+      • Persona: <Persona Name>: "<Persona reaction quote or consequence showing real human friction>"
+      • Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
+      • Recommendation: <Concrete recommendation from finding>
+
+   2. [MAJOR · hinders] Date picker has no "today" shortcut ([file](iamu/findings/<slug>.md))
+      • Persona: <Persona Name>: "<Persona reaction quote or consequence>"
+      • Evidence: Step <N> at <url>
+      • Recommendation: <Concrete recommendation from finding>
+
+   **Helps** (preserve these):
+
+   • [helps] Search auto-suggests from recent entries (Step <N>)
+
+4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
+
+5. **Next-scenario suggestion** — read `iamu/scenarios/` to check coverage, then suggest one of:
+   - Same scenario with a different persona (if other personas exist for this situation)
+   - Adjacent untested scenario in the same capability
+   - Nothing (if coverage is good)
+
+6. **Cloud** — one line, by mode:
+   - **Linked, run on the cloud** → `Shareable report: <url>` (screenshots and step replay for anyone on the team).
+   - **Linked, run not on the cloud** → the reason from step E and its remedy, e.g. `Cloud: queued — retries on the next iamu sync`.
+   - **Local-only** → on first completed run: `Want a link to share this report? iamu auth login connects to Iamu Cloud — optional, everything keeps working locally.`
+
+7. **Next actions (Interactive Triage Selection)**:
+   When the walkthrough completes and yields findings:
+   - If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+     - Question: "Walkthrough complete: <F> findings reported. How would you like to proceed?"
+     - Options:
+       1. "[Recommended] Walk through findings one by one"
+       2. "Apply fixes for all clear findings (batch fix)"
+       3. "Discuss findings and persona friction points"
+       4. "Re-run walkthrough to test changes"
+   - Otherwise (in CLI or text-only environments):
+
+   Walkthrough complete: <F> findings reported.
+     1. [Recommended] Walk through findings one by one
+     2. Apply fixes for all clear findings (batch fix)
+     3. Discuss findings and persona friction points
+     4. Re-run walkthrough to test changes
+
+   Press Enter to review findings [1], enter 2-4, or type specific instructions:
+   (Treat empty Enter as Option 1)
+
+### 6. Conversational Triage & Guided Review
+
+The conversation is the triage surface. Do NOT eject the user to manual CLI commands or dump them at file paths.
+
+#### A. Guided One-by-One Review ("walk through them" / "review one by one")
+When the user asks to review findings one by one:
+1. **Present Finding #N in isolation**:
+   - Number, severity, type, and title
+   - Persona consequence quote and why the friction occurred
+   - Relevant source code location (inspect project files to provide file path + line numbers)
+   - Step & screenshot evidence ([view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
+   - Actionable recommendation
+   - Interactive decision prompt:
+     - If interactive tool available:
+       - Question: "Triage Finding #<N>: '<finding title>'?"
+       - Options:
+         1. "[Recommended] Fix now (apply inline code fix & verify)"
+         2. "Dismiss / Skip (not relevant or walker error)"
+         3. "Discuss / Explore trade-offs"
+         4. "Next finding (keep open)"
+     - Otherwise (CLI / text-only):
+       Triage Finding #<N>: '<finding title>'
+         1. [Recommended] Fix now (apply inline code fix & verify)
+         2. Dismiss / Skip (not relevant or walker error)
+         3. Discuss / Explore trade-offs
+         4. Next finding (keep open)
+       Press Enter to fix [1], select 2-4, or describe decision:
+       (Treat empty Enter as Option 1)
+
+2. **Handle the user's decision**:
+   - **Fix now**:
+     Make the code edit, verify it loads (or check local tests/types), update the finding's frontmatter (`triage_status: addressed`, `triage_note: "<summary of fix>"`).
+     Tell the user the fix is applied and ask: "Ready for finding #<N+1>?".
+   - **Skip / Dismiss**:
+     If reason is not specified, ask or infer the appropriate category:
+     - `out_of_scope`: Not relevant to this project/flow scope.
+     - `not_relevant`: By design / intended behavior.
+     - `walker_error`: Walker misread the screen or made a navigational error.
+     - `duplicate`: Duplicate of another finding.
+     Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<why>"`.
+     Tell the user: "Dismissed as `<reason>` — created guidance rule in `iamu/guidance/<slug>.md` so future walkthroughs will not report this."
+     Then advance to finding #<N+1>.
+   - **Discuss / Why**:
+     Analyze why the persona experienced this friction, cite the persona brief and steps/screenshots, evaluate whether competitor tools solve this pattern, and give a direct opinion on whether it's worth fixing.
+   - **Next**:
+     Leave open (or set `triage_status: deferred` with note) and advance to finding #<N+1>.
+
+3. **Wrap up after all findings are reviewed**:
+   - Run `iamu validate --all`.
+   - In linked mode, run `iamu sync --json` once so teammates see the triage decisions.
+   - Suggest re-running the walkthrough: `iamu-run <scenario-slug>` to verify fixes.
+
+#### B. Direct Batch Actions ("fix 1 and 2", "fix all critical")
+Read the finding details from the canonical JSON (already in context), inspect the code, make the edits, and update frontmatter to `triage_status: addressed` with `triage_note`.
+
+#### C. Ad-hoc Questions & Challenges ("why did Karl do that?", "is #2 really a bug?")
+Answer directly using persona brief context and step evidence. If the walker got confused or misinterpreted intended behavior, recommend dismissing as `walker_error` or `not_relevant` rather than adding unnecessary code.
+
+**Linked mode: publish triage decisions.** When the user is done fixing and dismissing, run `iamu sync --json` once so teammates see the decisions (and any team request for these findings closes). Report it in one line (`Synced 3 findings to Iamu Cloud.`), with conflicts handled as in item 6. Do not sync after every single edit.
+
+**Do NOT** dump the user at file paths. The report and finding files exist for later reference, but the conversation is the triage surface. Mention artifacts only if the user asks for them or wants to share the report externally. The cloud link is the exception: in linked mode it IS the shareable report, so it always goes in the presentation.
+
+Run `iamu validate --all` to verify all entities before reporting done. If older finding files fail on schema drift (legacy status words, a finding type stored in `severity`, home-made ids), `iamu validate --all --fix` repairs what is mechanical — preview with `--dry-run`. Whatever it leaves invalid is missing information only a person has; report those, do not fill them in.
+
+## Guidelines
+
+- **Drafts bind in-line, not as a detour.** If the user picks a draft, the persona-bind step should feel like part of running — not a separate invocation.
+- **All generation is local.** All generation — persona suggestions, brief — uses the local LLM directly. No server-side LLM calls.
+- **Scenario vocabulary.** Say "scenario" — never "outline" — when addressing the user.
+- **Adopt, do not audit.** The walkthrough's value is seeing the product through the persona's eyes. Do not narrate as an observer — live it.
+- **The driving surface drives.** Every tool call that navigates the product goes through the driving surface picked in step 0. The `iamu` CLI records observations; it never drives.
+- **Close cleanly but stay present.** Canonical assembly ships the report + findings. Present findings inline and offer to fix — do not eject the user to files or another command. The conversation is the triage surface.
+- **Validate before done.** Always run `iamu validate --all` after a walkthrough to catch any issues.
+- **Use CLI for scaffolding.** `iamu start-run` for runs, `iamu new-finding` for findings, `iamu complete` for assembly. Never manually create run directories or generate UUIDs.
+- **Step files:** Record steps via the CLI (`iamu browse step` or `iamu step`), which manages step numbering, screenshots, and atomic writes to `steps/001.json`.
+- **Finding bodies:** After `iamu new-finding` scaffolds the file, edit the file to add the description and recommendation below the frontmatter.