@iamu-dev/iamu 0.2.0-beta.12 → 0.2.0-beta.13

package/dist/templates/prompts/walk.md

@@ -131,51 +131,49 @@ Your walking prompt has an `## Access` section saying how to become this persona
 
 ## Recording
 
-**Steps:** Write each step as a separate file using the Write tool:
-
-Path: `iamu/.runs/<run-id>/steps/<NNN>.json` (zero-padded, e.g., `001.json`, `002.json`)
-
-```json
-{
-  "step_number": 1,
-  "timestamp": "2026-04-27T10:00:00Z",
-  "action": "Opened dashboard",
-  "note": "First thing I see is...",
-  "screenshot": "screenshots/step-1.png",
-  "url": "https://app.example.com/dashboard",
-  "surface": "dashboard overview"
-}
-```
-
-`url` is the page you are on when the step ends — copy it from your driving surface (`iamu browse` prints it after every action), never reconstruct it. Record it on every step; it is how findings are grouped by page. Only a native app with no URL leaves it out.
+**Steps:** Record each step atomically via the CLI — never hand-craft raw JSON step files with custom scripts or host Write tools:
 
-`surface` is optional: a short name for the screen in the product's own words (`search results`, `checkout — payment`), not a description of what happened.
+- For `iamu browse`:
+  ```bash
+  iamu browse step --run <run-id> --action "<action>" --note "<first-person monologue>" <command> [args...]
+  ```
+- For other surfaces:
+  ```bash
+  iamu step --run <run-id> --action "<action>" --note "<first-person monologue>" [--shot <screenshot-path>] [--url <url>]
+  ```
 
-`timestamp` is the real time of the step — you have no clock of your own, so read it with `date -u +%Y-%m-%dT%H:%M:%SZ` rather than inventing one. Made-up times make a run impossible to line up with server logs.
+`action` is what you did (e.g. "Clicked Checkout button").
+`note` is your internal first-person persona reaction in character.
+The CLI automatically handles sequential numbering, timestamps, screenshot capture/linking, and live event streaming.
 
-One file per step. No appending. The Write tool creates the file without permission prompts.
-
-**Findings:** Always scaffold with the CLI — never create a finding file by hand, never invent an id:
+**Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools:
 
 ```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
+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 --description "Detailed markdown description of the issue" --recommendation "Concrete fix proposal" --json
 ```
 
-`--type` is one of `helps | hinders | missing | irrelevant | incorrect`. `--severity` is one of `critical | major | minor | observation`. They are different axes — a type is never a severity.
-
-Two more axes, both required on every finding:
+- `--type`: `helps | hinders | missing | irrelevant | incorrect`
+- `--severity`: `critical | major | minor | observation`
+- `--task-impact`: `blocks | impairs | slows | neutral | accelerates | enables`
+- `--confidence`: `high | medium | low`
+- `--description`: markdown body describing what happened and why
+- `--recommendation`: concrete suggestion for how to improve or fix the issue
 
-- `--task-impact` — what this does to the persona's task right now: `blocks` (cannot finish), `impairs` (finishes worse — wrong result, lost trust), `slows` (finishes, with needless effort), `neutral`, `accelerates` (faster than they expected), `enables` (could not have done it otherwise). A `helps` finding is `neutral`, `accelerates` or `enables`; a problem is never `accelerates` or `enables`.
-- `--confidence` — how sure you are this is real for this persona: `high` (you saw it on screen, clearly), `medium` (you saw it, but the persona might read it differently), `low` (it may be your tooling — say so in `consequence`). Then use the Edit tool to add the description and a `## Recommendation` section below the frontmatter. Leave `triage_status` alone; triage is not the walker's job.
+Leave `triage_status` alone; triage is not the walker's job.
 
-**Screenshots:** Save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` (pass an absolute path — some browser tools reject relative ones) before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking. A walkthrough with snapshots is better than no walkthrough.
+**Screenshots:** Screenshots are captured automatically by `iamu browse step`. If driving manually, save to `iamu/.runs/<run-id>/screenshots/step-<N>.png` before recording each step. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
 
-Use the Write tool for step files. Never use bash `cat`, `echo`, or heredocs to write files.
+**Execution rule:** Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.
 
 ## Synthesis
 
-After walking, compile:
-- **What worked** — Things the system did well for this persona. Important to preserve.
-- **Open questions** — Questions that arose that need discussion.
+After walking, record your synthesis using the CLI:
+
+```bash
+iamu summary <run-id> --worked "What worked well 1" --worked "What worked well 2" --question "Open question 1"
+```
+
+- `--worked` — Things the system did well for this persona. Important to preserve.
+- `--question` — Questions that arose that need discussion.
 
-Then return your summary so the orchestrating agent can run `iamu complete` and the evaluation stage.
+Then return your final summary to the orchestrating agent so it can run `iamu complete` and the evaluation stage.

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

@@ -67,27 +67,22 @@ Filter to `triage_status: open`.
 
 A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
 
-Group by `scenario` field and render with an executive tally header, followed by a severity-sorted list per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last), including persona quotes, evidence, and clickable file links:
+Group by `scenario` field and render with an executive tally header, followed by a compact, severity-sorted 1-line list per finding (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
 
 ```
 Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
 Awaiting verification: <K> addressed findings pending re-run
 
 ▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
-1. [CRITICAL · hinders] Handoff list is cluttered ([file](iamu/findings/<slug>.md))
-   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
-   • Evidence: Step <N> at <url>
-   • Recommendation: Add status filter chips
-
-2. [MAJOR · missing] No visible confirmation after shift submit ([file](iamu/findings/<slug>.md))
-   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
-   • Evidence: Step <N> at <url>
-   • Recommendation: Show inline success toast
+1. [CRITICAL · hinders] Handoff list is cluttered (Step <N>)
+2. [MAJOR · missing] No visible confirmation after shift submit (Step <N>)
 ```
 
+**ANTI-BLOAT DIRECTIVE:** Do NOT dump persona quotes, evidence URLs, or recommendations into the overview tally. Keep it strictly 1 line per finding so the user can scan it in 3 seconds.
+
 Ask the user how they would like to triage:
 
-- **"walk through them"** → iterate through all open findings one-by-one in order with full context, code location, and triage choices (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
+- **"walk through them"** → iterate through all open findings one-by-one in order with compact card (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
 - **"all critical"** → iterate through all critical findings in order.
 - **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
 - **Single number or slug** → single finding (skip to step 3).
@@ -113,27 +108,17 @@ Press Enter to walk through all [1], select 2-3, or enter a finding number/slug:
 
 ### 3. Direct triage: review one finding
 
-Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Inspect the codebase to identify the source file and line responsible. Render full detail with clickable links and evidence:
+Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Inspect the codebase to identify the source file and line responsible. Render a compact, 4-line triage card:
 
 ```
-Finding: <title> ([file](iamu/findings/<slug>.md))
-Scenario: [<scenario>](iamu/scenarios/<scenario>.md)
-Severity: <severity> · Type: <type> · Status: <triage_status>
-
-Persona Quote: "<persona_reaction_or_consequence>"
-UI Fact: <ui_fact>
-Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run>/screenshots/<NNN>.png))
+Finding: [<SEVERITY> · <type>] <title> ([file](iamu/findings/<slug>.md))
+Friction: <Persona Name>: "<1-sentence reaction or consequence quote>"
 Source: <file:line path in repository, e.g. src/components/HandoffModal.tsx:42>
-
-Description:
-<markdown body above ## Recommendation>
-
-Recommendation:
-<## Recommendation section, or "none">
-
-Report: [report.md](iamu/.runs/<run>/report.md)
+Proposal: <1-sentence concrete fix recommendation>
 ```
 
+Do NOT dump raw markdown bodies, multi-paragraph descriptions, or file link lists. Keep the triage card under 5 lines so the decision prompt is immediately visible without scrolling.
+
 If the finding references a run directory, mention the report path for context. If the user wants to see the screenshot, read from `iamu/.runs/<run>/screenshots/`.
 
 ### 4. Prompt for triage action
@@ -177,7 +162,7 @@ triage_status: addressed
 triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 ```
 
-- **Fix now** → the change is small, one-or-two files, no architectural decision needed (label, field made optional, filter added, typo). Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then update frontmatter: `triage_status: addressed` with a one-line change summary in `triage_note`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
+- **Fix now** → the change is small, one-or-two files, no architectural decision needed (label, field made optional, filter added, typo). Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then record: `iamu triage <slug> --status addressed --note "<one-line change summary>"`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
 
 - **Design change needed** → the change requires design thinking (restructuring a flow, new capability, API contract touch, multiple files). Do NOT fix inline. Use the project's own change process if it has one — check the agent docs and the repo for it (an `openspec/` directory and its change skills, an ADR or RFC folder, an issue tracker the docs name) and start the change there with the finding's persona + scenario context pre-filled. Only if the project has none, draft a short design doc. Then leave the finding `open` until the change ships. Attach the change reference in `triage_note`: `"Design change: <reference>. Re-triage when the change ships."`.
 

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

@@ -229,7 +229,7 @@ The result's `walker_prompt` is the walker's entire prompt. Pass it verbatim —
 
 **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.
+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 and a shell for `iamu` commands. The walker never needs direct host file-editing tools: all steps, findings, and summaries are recorded atomically via CLI 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.
@@ -291,15 +291,13 @@ Step files live at `iamu/.runs/<run-id>/steps/<NNN>.json`. The CLI manages monot
 
 **Recording findings:**
 
-Use the CLI to create findings with valid frontmatter, UUID, and slug:
+Use the CLI to create findings with valid frontmatter, UUID, slug, description, and recommendation in one atomic call:
 
 ```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
+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 --description "Detailed markdown description" --recommendation "Concrete fix proposal" --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.
+This generates a valid UUID, derives the slug from the title, and writes the complete finding file to `iamu/findings/<slug>.md`. Returns `{ "slug": "...", "path": "...", "id": "..." }`. Never invoke host Edit or Write tools.
 
 Valid `--type` values: `helps`, `hinders`, `missing`, `irrelevant`, `incorrect`.
 Valid `--severity` values: `critical`, `major`, `minor`, `observation`.
@@ -310,6 +308,12 @@ Findings never name a human test: the walker does not see them. The judge links
 
 **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.
 
+**Closing Synthesis:**
+Before finishing the walk, record persona synthesis using `iamu summary`:
+```bash
+iamu summary <run-id> --worked "What worked well 1" --worked "What worked well 2" --question "Open question 1"
+```
+
 **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.
@@ -328,10 +332,11 @@ This reads all steps, findings, and entity files, assembles `canonical.json`, ge
 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:
+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). Record its JSON answer via `--data` (or `--file`):
 
 ```bash
-iamu match-record <run-id> --file <matches.json>
+iamu match-record <run-id> --data '<matches.json>'
+# or: 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.
@@ -342,10 +347,11 @@ This links recurrences to their earlier canonical finding, marks earlier finding
 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`:
+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` via `--data` (or `--file`):
 
 ```bash
-iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
+iamu evaluate-record <run-id> --data '<verdicts.json>' --no-prompt --no-push
+# or: 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.
@@ -380,59 +386,28 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 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>
+Render results **inline** as a concise executive scorecard.
 
-   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>
+**ANTI-BLOAT DIRECTIVE:** Terminal viewports are small. Never output multi-screen walls of markdown text. The overview exists only to present the top-line score and orient the user for triage. Do NOT dump long quotes, recommendations, full descriptions, or "What Worked" essays here — those belong in the interactive triage step below.
 
-   **Helps** (preserve these):
+Keep the presentation under 15 lines total:
 
-   • [helps] Search auto-suggests from recent entries (Step <N>)
+```
+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-sentence direct answer>
 
-4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
+Findings:
+1. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
+2. [<CRITICAL|MAJOR|MINOR> · <type>] <Short title> (Step <N> at <short_url_path>)
+...
+(Helps: • [helps] <short title> (Step <N>))
 
-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)
+Cloud: <Shareable report: <url> | Local only>
+```
 
-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.`
+(If canonical.json contains a `verification` section, include a 1-line delta: `Since last run: ✓ <N> fixed · ✗ <M> persist · + <K> new`.)
+Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the entire summary under 15 lines, then immediately present the triage prompt below.
 
 7. **Next actions (Interactive Triage Selection)**:
    When the walkthrough completes and yields findings:
@@ -460,20 +435,21 @@ The conversation is the triage surface. Do NOT eject the user to manual CLI comm
 
 #### 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)"
+1. **Present Finding #N in a compact card (maximum 4 lines):**
+   ```
+   Finding <N>/<total>: [<SEVERITY> · <type>] <title>
+   Friction: <Persona Name>: "<1-sentence reaction quote>"
+   Location: <file:line path in repository, e.g. frontend/src/components/Form.tsx:309>
+   Proposal: <1-sentence concrete fix recommendation>
+   ```
+   Followed immediately by the 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)
@@ -485,8 +461,8 @@ When the user asks to review findings one by one:
 
 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>?".
+     Make the code edit, verify it loads (or check local tests/types), update the finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+     Tell the user in 1 line: "✓ Applied fix to `<file>:<line>`. Finding #<N> marked addressed." 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.
@@ -494,10 +470,14 @@ When the user asks to review findings one by one:
      - `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."
+     Tell the user in 1 line: "✓ Dismissed as `<reason>` — guidance rule recorded."
      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.
+   - **Discuss / Why (STRICT CONSTRAINT: maximum 3-4 concise bullets, under 80 words total)**:
+     Never write multi-section essays, markdown headers (`### Trade-off Analysis`, `#### 1. Why it was built this way`, `#### 2. The Operational Failure`), or ASCII/markdown tables. Deliver a direct, surgical 3-bullet answer:
+     • **Root Cause:** 1 sentence on why the code does this (`file:line`).
+     • **Persona Friction:** 1 sentence on the practical operational consequence.
+     • **Recommended Fix & Trade-off:** 1-2 sentences with concrete code approach and any trade-off.
+     Immediately re-prompt the triage decision.
    - **Next**:
      Leave open (or set `triage_status: deferred` with note) and advance to finding #<N+1>.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.12",
+  "version": "0.2.0-beta.13",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,9 +58,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/protocol": "0.1.0",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu/tsconfig": "0.1.0"
+    "@iamu/tsconfig": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b --force tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",