@iamu-dev/iamu 0.2.0-beta.1 → 0.2.0-beta.10

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

@@ -46,11 +46,23 @@ If no surface is available, stop and tell the user:
 
 Do NOT proceed to step 1 before a driving surface is confirmed.
 
-**Unfinished runs.** Run `iamu status --json` and look at `runs.incomplete`. A run listed there was started but never reached `iamu complete` — the walker died or the session ended — so its steps and findings exist but it has no report, no verdicts, and no delta. If there are any, tell the user how many and offer, once:
+**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.
 
-- **Finish** one that has step files: run the post-walk pipeline (step 4, A→B→C→D) on it as it stands. A partial walk with a report is worth more than a complete one nobody assembled.
-- **Discard** ones with no steps: delete the run directory. Runs are ephemeral; findings already written to `iamu/findings/` are kept.
-- **Leave them** and carry on.
+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.
 
@@ -84,15 +96,31 @@ Ready to run:
   4. dev-patel--checkout-abandon — Abandoned cart x Dev Patel
 ```
 
-Omit the first group when `rerun` is empty. User picks a number or slug. Drafts get a bind prompt before execution (step 2); ready-to-run scenarios skip to step 3.
+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."
 
-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.
+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:
 
-"This scenario is a draft — no persona bound. Pick one, or draft a new persona."
+**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.
@@ -113,7 +141,11 @@ After bind + brief, the scenario is ready to execute. Continue to step 3.
 
 ### 3. Target
 
-**Web** — ask for the target URL (live product, staging, or localhost). If the scenario has a default `target_url` in its frontmatter, offer that with a confirm.
+**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.
 
@@ -127,19 +159,30 @@ Record it as a target string the run can carry, for example `sim://<device-name>
 
 **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.
 
-**Web: check the product is ready, not just up.** A server that answers is not a product that has its data. Before spawning the walker, confirm the thing the scenario depends on actually exists — the list the persona will open is populated, the seeded records are there, background setup (seeding, migrations, indexing) has finished. Use the project's documented readiness signal if it has one; otherwise look at one screen or one API response yourself. A walk started too early reports "the feature is missing" as a critical finding, and nothing in the walker's view distinguishes that from a real defect.
+**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).
 
-If both are present, use them as they are. If either is missing, fill the gap now and SAVE it so no later run has to ask:
+**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.
 
-1. Check the project's own agent docs (`CLAUDE.md`, `AGENTS.md`, anything they point to for the dev environment) 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 — a persona the product cannot represent is itself worth telling the user.
-3. If the docs are silent, ask the user once. "No login, everyone is the same user" is a valid answer.
-4. 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.
+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.
 
@@ -185,12 +228,16 @@ The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim —
 
 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>", prompt: "<walker_prompt, verbatim>" })
+Agent({ description: "Walk <scenario-slug> as <persona.name>", model: "haiku", prompt: "<walker_prompt, verbatim>" })
 
 # In Antigravity / generic subagent hosts:
-invoke_subagent(Role="Persona Walker", Prompt="<walker_prompt, verbatim>")
+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.
@@ -202,7 +249,7 @@ The subagent inherits the driving-surface tools and drives the product independe
 - **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 is not supported by your host editor** (e.g. standard Cursor without subagent tools), fall back to walking in the same context — but strictly adhere to the persona behavioral constraints in `walker_prompt`.
+**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.
 
@@ -215,6 +262,12 @@ Use atomic CLI commands to drive and record in one step — do NOT manually auth
   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):**
@@ -249,26 +302,21 @@ Findings never name a human test: the walker does not see them. The judge links
 
 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.** Use the CLI:
+**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
 
 ```bash
-iamu complete <run-id> --no-prompt
+iamu complete <run-id> --no-prompt --no-push --json
 ```
 
-This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, computes the delta against prior runs, and flips the manifest to completed. All in one command.
-
-To get the canonical data for presentation, run with `--json`:
-```bash
-iamu complete <run-id> --no-prompt --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.** A fresh walker never words a recurring problem the same way twice, so `complete` alone reports recurrences as new and earlier findings as "not seen". Get the matcher bundle:
+**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 dispatch a matcher subagent with `match_prompt` as its only context — NOT the walker, which must never see earlier findings. Write its JSON answer to a file and record it:
+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>
@@ -276,23 +324,23 @@ 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.** Use the CLI to get the evaluation prompt:
+**C. Evaluate human tests.** Get the evaluation prompt:
 
 ```bash
 iamu evaluate <run-id> --json
 ```
 
-This returns the judge prompt input bundle. Dispatch the evaluator as a subagent with that prompt. After the evaluator returns verdicts, record them:
+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
+iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
 ```
 
-This also links the findings each verdict cites to that human test (`human_test_id` on the finding file, only where none is set), so `iamu sync` carries the link to the cloud.
+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).** `complete` and `evaluate-record` already pushed the run itself — report, steps, screenshots, verdicts. What they do not push are the finding files the matcher and judge updated (recurrence links, `human_test_id`); those go with sync:
+**E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
 
 ```bash
 iamu sync --json
@@ -320,15 +368,17 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 5. Present assessment — stay in the conversation
 
-Render results **inline** so the user can act without leaving the conversation. Lead with the overall assessment, not a findings dump.
+Render results **inline** with a high-contrast executive summary banner, followed by findings enriched with persona voice, evidence citations, and clickable file links.
 
-1. **Overall assessment** — answer the research question from the outline's human test. Read the outline's `human_tests[0].question` (the focus question the user defined when creating the scenario). Frame the verdict around it:
+1. **Executive Summary Banner & Focus Checkpoint**
 
-   > **Could the admin complete bulk-import without consulting documentation?** No. The import flow requires knowledge of the role hierarchy that isn't documented in-app. 3 issues found, 1 critical.
+   Read the outline's `human_tests[0].question` and answer it directly. Use the evaluation verdict if available:
 
-   If the evaluation subagent ran, use its verdict. If it failed or wasn't run, synthesize from findings: count hinders/missing by severity, state whether the persona could complete their task.
-
-   **This is the most important part of the output.** The user defined this question as their focus — answer it directly.
+   ```
+   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:
 
@@ -340,25 +390,25 @@ Render results **inline** so the user can act without leaving the conversation.
      + 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. `iamu complete` reports whether the walk reached the places where fixes await a re-run (`Re-check places: reached N of M`, `revisit_coverage` in `--json`); name the ones not reached — their fixes stay awaiting.
-
-   If no prior run exists, skip this.
+   `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 — the actionable ones — then helps at the bottom):
+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):
 
-   | # | Severity | Type | Finding | Recommendation |
-   |---|----------|------|---------|----------------|
-   | 1 | CRITICAL | hinders | Submit fails opaquely when required field empty | Show validation inline before submit |
-   | 2 | MAJOR | hinders | Date picker has no "today" shortcut | Add quick-select for common dates |
-   | 3 | MINOR | missing | Help text uses jargon ("slutdatum") | Use plain language ("end date") |
+   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):
 
-   | # | Type | Finding |
-   |---|------|---------|
-   | 4 | helps | Search auto-suggests from recent entries |
+   • [helps] Search auto-suggests from recent entries (Step <N>)
 
 4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
 
@@ -369,16 +419,86 @@ Render results **inline** so the user can act without leaving the conversation.
 
 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` or `Cloud: not pushed — <reason>`.
-   - **Linked, no credentials** → `Cloud: not pushed — this machine has no credentials; iamu auth login restores them.`
-   - **Sync conflicts or pending deletions** (step E) → one line each: name the findings a teammate changed and give the CLI's resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours — the user runs that one); for deletions, tell the user to review them and run `iamu sync --confirm-deletes` themselves.
-   - **Local-only** → nothing, with one exception: on the project's first completed run (`iamu status --json` → `runs.count` is 1), add `Want a link to share this report? iamu auth login connects the project to Iamu Cloud — optional, everything keeps working locally.` Never repeat it on later runs unless the user asks how to share a report.
-
-7. **End with a verb**: "Which ones should I fix? (You can also dismiss any finding — it won't show up in future runs.)"
-
-**Stay conversational.** The user says "fix 1 and 2" → you read the finding details from the canonical JSON (already in your context from the canonical assembly), look at the relevant code, and make the fix. Mark findings addressed by editing their frontmatter (`triage_status: addressed`, `triage_note: "..."`) as you go.
-
-If the user says "skip 3" or "not relevant" or "dismiss" for a finding, set `triage_status: dismissed` with a `triage_note` explaining why. **Tell the user:** "Dismissed — this won't be reported in any future walkthrough."
+   - **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.