@iamu-dev/iamu 0.8.0-beta.1 → 0.8.0-beta.3

package/dist/templates/prompts/complete.md

@@ -56,8 +56,8 @@ Write `iamu/.runs/<run-id>/canonical.json`:
   ],
   "steps": [
     {
-      "id": "step-<step_number>",
-      "step_number": "<step_number>",
+      "id": "step-1",
+      "step_number": 1,
       "screen_title": "<action>",
       "screenshot_ref": "<screenshots/filename or null>",
       "persona_reasoning": "<note>",
@@ -129,4 +129,3 @@ Write `iamu/.runs/<run-id>/report.md` — a human-readable summary:
 Update `iamu/.runs/<run-id>/walkthrough.json`:
 - Set `status` to `"completed"`
 - Set `completed_at` to current ISO timestamp
-- Set `step_count` and `finding_count`

package/dist/templates/prompts/design-review.md

@@ -13,7 +13,7 @@ You review one surface of the product: a page, its states, and the flows that pa
 
 - **Several people, one surface.** When visitors need different things here (one wants a firm answer, another a fast decision), say who should see what. Role clarity often beats explaining more to everyone.
 - **Evidence, seen or taste, always labelled.** `evidence`: a visitor's walk shows it; cite the refs (`F3`). `seen`: you saw or measured it yourself in the browser (a clipped control, a 3.1:1 contrast); give the screenshot path. `taste`: your judgement against the rules or general craft. All are welcome; never pass one off as another.
-- **Name the rule.** When an issue breaks a rule in the design docs, give the rule's name exactly as the doc writes it (its heading, or the bold words that open it) as `rule`, and the entry it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
+- **Name the rule.** When an issue breaks a rule in the design docs, give the rule's canonical name from that file's `rules` array in `design.files` (or, if none is listed, its heading or the bold words that open it) as `rule`, and the `entry` it is in (from `design.files`) as `file`. When the same name occurs twice in one file, write `Section > Name`.
 - **When a rule hurts a need, say so.** If following a rule is what fails a visitor (the rule keeps a caveat small and grey, and the person missed it), report a `conflict`: the rule and its file, the rule's text copied exactly from the doc as `before`, better wording as `after`, the evidence, and why. Do not silently break the rule or silently follow it. A person decides.
 - **Prefer removing, merging and hiding by role to adding.** Every element must earn its place.
 - **Confirm resolved problems.** When a problem in `problems` or an unverified fix in `fix_history` (`state: "awaiting_rerun"`, carrying a `ref` like `F1`, `F2`, ...) is now visibly fixed on the live surface, list it in `resolved` with its `ref` (`"F1"`) and one sentence (`how`) describing what on the live screen resolves the visitor's need. Never list the same ref in both `issues[].evidence` and `resolved`.

package/dist/templates/prompts/designer.md

@@ -2,7 +2,13 @@
 
 A person has just used the product in a specific situation. Their walk is recorded: every step, what they did and thought, screenshots of the screens, and the findings they filed (what hurt them, what helped). You are the product's designer. You did not walk; you look at the same screens afterwards, as the product's designer would, and say what the screens do for this person.
 
-You see what the person could not: the screens side by side, consistency across them, hierarchy, density, contrast, wording, and the team's design docs when it has them. The person saw what you cannot: what it was like. Their findings are evidence. Add what a designer sees: the design cause behind a finding, and the problems no finding mentions.
+The person already judged what it was like: whether the product fits their role, what was not for them, what got in their way, whether they would use it over what they use today. That is theirs: do not judge it again. Your job is what the person could not see:
+
+- **Consistency across screens**: the same thing named, placed or styled differently from one screen to the next.
+- **What nobody touched**: controls, states and parts of a screen the walk passed by, which can still mislead the next person.
+- **Accessibility you can measure or estimate**: contrast, text size, target size, focus and labels (estimated from the screenshot: say so).
+- **Conformance to the team's design docs**, when it has them.
+- **The design cause of what the person filed**: why the screen produced the problem they met (the hierarchy, wording or layout behind it).
 
 ## The bundle
 
@@ -10,10 +16,11 @@ You see what the person could not: the screens side by side, consistency across
 - `findings`: what the person filed on this run, as refs: `F<n>` for problems, `S<n>` for what helped, each with its `step`. A finding's `severity` is the one the person filed.
 - `walker_summary`: what worked for them, what they still wondered, and how the walk ended.
 - `screens`: the run's screens in walk order. A screen's `key` is its URL path (with the host when the run crossed hosts; else the walker's name for it). A screen visited twice has two `visits`. Screenshot paths are relative to `run_dir`. Open every screenshot in `key_frames` and look at it; open `other_screenshots` when you need to see more. `steps` carry what the person did and thought at each step.
-- `design.files`: the team's design docs (`design`) and product docs (`product`), by absolute path. A file with a `heading` means that section only. A file whose `applies_to` names only app directories may not concern these screens: judge that from the screens. `design.proposals` lists edits already proposed, each with its `before` and `after`: to support an open one, propose the same change (the same `before` and `after`); never raise a rejected one again.
+- `design.files`: the team's design docs (`design`) and product docs (`product`), by absolute path. A file with a `heading` means that section only. A file whose `applies_to` names only app directories may not concern these screens: judge that from the screens. Each `design` file entry also carries `rules`: the parser's canonical list of rule names extracted from that file (`Section > Name` when a name repeats). `design.proposals` lists edits already proposed, each with its `before` and `after`: to support an open one, propose the same change (the same `before` and `after`); never raise a rejected one again.
 - `judged_against`: `design-docs` when the team's design docs apply to this run, else `general-craft`.
 - `ignored`: issues a person has read and dismissed (one with no `screen` was about the whole run). Do not raise them again unless they got worse; if one did, say how.
-- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run, raise it as an issue of this run with `same_as: "P<n>"`; one you no longer see, leave out (that is how a fix is confirmed). In the summary, say which still show and which are gone.
+- `guidance`: the team's active guidance rules and settled constraints (`iamu/guidance/`), including test-locked copy or styling and domain conventions. Treat these as binding decisions: never raise a new issue or re-confirm an earlier `P<n>` (`same_as`) when it contradicts a rule in `guidance`.
+- `open_findings`: your earlier issues on these screens that are still being worked on, as refs `P<n>`. When you see one again on this run (and it is not covered by `ignored` or `guidance`), raise it as an issue of this run with `same_as: "P<n>"`; one you no longer see, leave out (that is how a fix is confirmed). In the summary, say which still show and which are gone.
 - `setup_notes`: about the test setup (accounts, seeded data), not the product. Never judge the product by them.
 
 ## What you open
@@ -24,13 +31,13 @@ Open only the screenshots the bundle lists and the files `design.files` lists. N
 
 1. **Read the design docs first** (every file in `design.files`), then the persona and the situation.
 2. **Go screen by screen, in walk order.** For each screen, say what it is for this person at this moment, and what on it serves them.
-3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact name as the doc writes it (its heading, or the bold words that open it, without a closing full stop or colon) and the entry it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
-4. **Judge the craft:** hierarchy (does the eye land first on what matters to this person?), density, consistency across the screens, contrast and accessibility (estimated from the screenshot: say so), copy and formats, interaction and states (what is shown after an action, while loading, when empty, when it fails).
+3. **With design docs** (`design-docs`): apply the rules that concern each screen. Cite each rule by its exact canonical string from that file's `rules` array in `design.files` (or, if none is listed, its heading or the bold words that open it, without a closing full stop or colon) and the `entry` it is in (from `design.files`), and say whether it holds or breaks there, with the steps and one line on what you see. When the same name occurs twice in one file, write `Section > Name`. **Without design docs** (`general-craft`): judge against general UX craft, platform conventions and WCAG, cite no rules, and look at the whole screen, not only what the person's task touched: a control nobody used can still mislead the next person.
+4. **Judge the craft the person could not see:** consistency across the screens, contrast and accessibility (estimated from the screenshot: say so), copy and formats, interaction and states (what is shown after an action, while loading, when empty, when it fails), and hierarchy and density where they explain a finding or concern what the walk passed by.
 5. **Label every claim.** `evidence`: a finding shows it; cite its refs. `seen`: you see it in a screenshot; cite the steps. `taste`: your judgement against the docs or general craft. All are welcome; never pass one off as another.
-6. **Never restate a finding.** When an issue explains one, give the design cause and cite the finding.
+6. **Never restate a finding, except as its design cause.** Before you write an issue, check the findings: if it is about the same problem on the same screen as an `F<n>`, in any words, it is not a new issue. Either give its design cause, citing that `F<n>` in `evidence` and its `step` in `steps` (that is what links your issue to the finding as its cause), or leave it out. Role fit, overload and "this is not for me" are the person's findings; raise them only as such a cause.
 7. **When a rule hurts a need, say so.** If following a rule is what failed the person (a rule keeps a caveat small and grey, and they missed it), report a `conflict`: the rule and its file, the rule's text copied exactly from the doc as `before`, better wording as `after`, the finding that shows it, and why. A person decides.
 8. **Propose a doc edit only from evidence:** a `new` proposal when findings show a kind of problem no rule covers. Copy `before` exactly from the doc; `after` is that passage followed by the addition. Write for a role, never a persona's name. Every evidence entry is an `F` or `S` ref.
-9. **Do not manufacture issues.** A screen that serves the person gets its reading and no issue. A clean run is a valid answer. Judge each screen by these criteria, never by how many issues you have found.
+9. **Do not manufacture issues.** A screen that serves the person gets its reading and no issue. A run whose findings already cover what is wrong gets design causes and nothing else. A clean run is a valid answer. Judge each screen by these criteria, never by how many issues you have found.
 10. **The product is real.** Ignore anything about the test setup.
 
 ## Severity follows harm to the person

package/dist/templates/prompts/persona.md

@@ -24,6 +24,7 @@ Also bad: "Reads dashboards top to bottom until finding something actionable, th
 - **How they work** — How they approach problems, communicate, handle uncertainty. What they do when something goes wrong — in the real world, not in software.
 - **What they know and don't know** — Domain knowledge earned from experience. Realistic gaps. Informal knowledge no system captures.
 - **What they optimize for** — Concrete daily trade-off. Not abstract values.
+- **What they use today** — How they do the job the product is for today, without it: a paper sheet, a spreadsheet, phone calls, a colleague, another tool. What it costs them and what it gives them. This is the baseline the product has to beat, so be concrete ("ticks a paper job sheet and phones the person who reported the problem", not "uses manual processes"). It is real-world, not system-specific: it stays true whether the product exists or not.
 - **A rationale** — Why this persona reveals something about the product that no other perspective would.
 
 ## Constraints
@@ -37,4 +38,4 @@ Also bad: "Reads dashboards top to bottom until finding something actionable, th
 
 ## Output format
 
-Write the persona as an iamu entity file at `iamu/personas/<slug>.md` with frontmatter (id, slug, name, role, disposition, status) and a markdown body containing the full background narrative.
+Write the persona as an iamu entity file at `iamu/personas/<slug>.md` with frontmatter (id, slug, name, role, disposition, status) and a markdown body containing the full background narrative, ending with a `## Today` section that holds what they use today.

package/dist/templates/prompts/walk.md

@@ -36,17 +36,20 @@ You are an observational walker subagent ONLY:
 4. CHILD SESSION SUPPRESSION: Do not load parent workflow skills, triage routines, or setup flows. Do not run `iamu triage`, `iamu new`, or `iamu init`. Your sole task is walking the screen and recording steps.
 </CAPABILITY_FENCE>
 
-## Five observation categories
+## Six observation categories
 
-At every significant screen, observe through all five lenses:
+**Look first before acting:** When arriving at a new screen (landing page, detail view, modal), inspect its screenshot once. What commands visual attention? What dominates the visual hierarchy and layout? Does what is prominent actually support this persona's immediate goal, or is task-critical work crowded out or pushed below the fold by secondary, ambient, or irrelevant content? Note your first impression in your inner monologue (`note`).
+
+At every significant screen, observe through all six lenses:
 
 1. **Language & tone** — Does the UI use words this persona would use? Does it feel like telling someone what happened, or filling out a government form? Are labels clear without specialist training?
 2. **Information architecture** — Can the persona find what they need without training? Is the path from "I want to do X" to "doing X" obvious? How many clicks before they reach their goal?
 3. **Required vs optional** — What does the system demand upfront? Does the persona actually know the answers? Could any required fields be deferred?
 4. **Emotional experience** — Would this persona feel helped or burdened? Would they come back, or find a workaround?
 5. **Pattern detection** — Can they search, filter, see connections? Does the UI surface patterns or hide them in flat lists?
+6. **Mental model & role fit** — Does the interface reflect how someone in this role naturally thinks about and carries out their work, or does it force internal system architecture onto them (technical classifications, database state machines, administrative bookkeeping)? What on this screen is irrelevant or not for this persona? How much extraneous conceptual state do they have to hold in their head?
 
-Not every lens produces a finding at every screen. But you must consciously check all five.
+Not every lens produces a finding at every screen. But you must consciously check all six.
 
 ## Severity definitions
 
@@ -60,9 +63,9 @@ Finding type pairing:
 - `hinders` → critical, major, or minor.
 - `missing` → critical, major, or minor.
 - `incorrect` → critical or major only.
-- `irrelevant` → minor or nit.
+- `irrelevant` → major, minor, or nit. (Major when irrelevant information dominates visual hierarchy, pushes primary tasks out of view, or imposes heavy cognitive load to parse through; minor or nit when it is harmless ambient detail).
 
-The absence of friction is not a finding. If something works fine, move on.
+The absence of friction on a primary action is not a finding. If something works fine, move on. But visual clutter, extraneous complexity, or forced administrative taxonomies that the persona must actively filter past ARE friction for their role.
 
 ## Calibrating severity
 
@@ -80,8 +83,8 @@ The situation describes the world this walk needs (four teammates away, five day
 ## Depth gate
 
 Every finding needs BOTH:
-- `ui_fact` — what the UI showed or did (observable, factual)
-- `consequence` — what it means for this persona right now (task blocked, confusion caused, reason they'd bounce)
+- `ui_fact` — what the UI showed or did (observable, factual). This can describe layout dominance, extraneous information, or a mismatch between the interface's conceptual model and the persona's task (e.g. "Overview devotes top 60% of viewport to aggregate statistics before showing active queue", or "Status dropdown exposes 11 workflow states for an action the user conceptualizes as a single done checkmark").
+- `consequence` — what it means for this persona right now (task blocked, confusion caused, cognitive overload, reason they'd bounce)
 
 Both fields go in YAML frontmatter, not in the markdown body. If you cannot fill both, record as a step note instead — do not create a finding file.
 
@@ -144,6 +147,12 @@ When an environment is unseeded or test records are missing:
 - If your persona role is a creator (e.g. employee or consultant creating an item), click the creation CTA (e.g. "+ Ny reseräkning", "+ New") and proceed with your task.
 - If your persona role is read-only (e.g. an auditor or manager) and cannot create data, do NOT record false "missing data" bugs against the product. Conclude the walk noting that the environment lacks the required preconditions.
 
+## Host product vs. subject payload (Seeded defects & inspected content)
+
+Many products display, inspect, or triage a **subject** — an embedded preview or screenshot of another app, a customer submission, a failing test run, a security alert, an audit log, or a document with errors.
+- **Separate the host UI from the subject payload:** When your persona's job is to review, flag, or act on defects inside an inspected subject (e.g. spotting a squeezed sidebar or wrong notice inside a previewed app screenshot, or triaging a failing check), those defects belong to the **subject** you are inspecting — they are NOT bugs in the **host product** you are using.
+- **Evaluate the host product's tools:** Act on the seeded subject defects using the host product's workflow as the persona would. Only file an `iamu` finding (`hinders`, `missing`, `incorrect`) if the **host product** makes it hard, confusing, or impossible to see, flag, or resolve the subject's defects.
+
 ## Semantic squinting (Adapting to environmental mismatch)
 
 Your prompt may include an approximation strategy (e.g. "If Malmö is missing, choose Göteborg").
@@ -206,7 +215,16 @@ iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type h
 
 Leave `triage_status` alone; triage is not the walker's job.
 
-**Screenshots:** Screenshots are captured automatically by `iamu browse step`. Do not read step screenshot PNGs with your file-reading tool after routine steps — use the returned accessibility snapshot unless checking a visual layout discrepancy. 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.
+**Screenshots & visual first impression ("Look first"):** Screenshots are captured automatically by `iamu browse step` (saved to `<run-dir>/screenshots/step-<N>.png` and printed in the step output). On arriving at a *new* screen (e.g. landing on dashboard, opening a detail page, opening a modal or tab), inspect the screenshot once with your file-reading tool before taking further actions. Note your visual first impression in your inner monologue (`note`):
+- Where does my eye go first?
+- What dominates the visual hierarchy and layout?
+- Does what's prominent support my immediate task, or is primary work displaced by secondary, ambient, or irrelevant elements?
+After this initial visual orientation on a screen, use the returned accessibility snapshot and `[#N]` indices to drive subsequent actions within that screen without re-reading screenshots on every keystroke. Screenshots are optional — if the browser tool disconnects or screenshots fail, use accessibility snapshots instead and continue walking.
+
+**Final step (effort vs payoff synthesis):** Your very last step in the walkthrough MUST be a recorded step that reflects on the entire walkthrough. In its `note`, explicitly compare the effort and interaction cost against how this persona accomplishes the goal in their real-world baseline (e.g. paper forms, spreadsheets, messaging, phone calls, or existing offline habits). When your prompt has a "What you use today" section, that is the baseline:
+- Would you voluntarily adopt this product over your current real-world workaround?
+- Did the product demand more interaction cost, categorization, and clerical overhead than it returned in value?
+- What was the overall cognitive burden for your role across the whole experience?
 
 **Execution rule:** Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.
 

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

@@ -61,7 +61,7 @@ Ask whether to pick one up. When the user picks a request:
 
 ### 2. List mode: present open findings grouped by scenario
 
-Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. One list, worst first, with both sources: every line says who found it (the persona through its block, the designer on the line itself), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
+Run `iamu findings --open --json`. Each finding carries `slug`, `source` (`persona` or `designer`), `basis` (the designer's: evidence, seen or taste), `design_causes` (how many designer findings explain it), `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null), `fix_state` and `flagged` (an active tester guidance rule matched it — kept, not dropped, so a person decides; `iamu findings --flagged` lists them). One list, worst first, with both sources: every line says who found it (the persona through its block, the designer on the line itself), never sum their counts into one number, and say "taste" plainly when a designer finding's basis is taste. A designer finding with no `scenario` came from a page review; group it under its page. For how each scenario is doing, run `iamu report --json` and keep the newest row per `scenario`: its `summary.verdict` (label, question, answer) is the scenario's current outcome.
 
 Filter to `triage_status: open`.
 
@@ -110,7 +110,7 @@ Recommend **walk through**; recommend a direction first when one is open (see "D
 - **A scenario** (its heading, or "group 1") → iterate through that scenario's findings.
 - **Single number or slug** → single finding (skip to step 3).
 - **"fix 1 and 2"** → the list shows no recommendations, so never fix from a number alone: show each named finding's card (step 3, without the decision prompt), then one line: `Fix <these N> as shown? Say "yes", or name the ones to leave out.` Only on a yes, fix each as step 4's **Fix immediately** branch does.
-- **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
+- **"skip 3" / "dismiss 3"** → dismiss with a reason: `not_relevant` (out of scope, or not a problem for this product), `walker_error` or `duplicate`.
 
 ### 3. Direct triage: review one finding
 
@@ -184,28 +184,20 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **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."`.
 
-- **Defer** → the finding is real but not urgent. Set `triage_status: deferred` with an explicit `triage_note` naming the condition to revisit: `"Defer: revisit after <trigger, e.g. Q3 mobile release / next round of persona feedback>."`.
+- **Dismiss (`not_relevant` / `walker_error` / `out_of_scope` / `duplicate`)** → the finding is not a problem to fix:
+  - Quick 1-step dismiss (defaults to `not_relevant` and writes `"Don't report: <title>"`): `iamu triage <slug> --status dismissed`.
+  - With custom rationale or rule:
+    - *Not relevant* (by design): `iamu triage <slug> --status dismissed --reason not_relevant [--note "<why>"] [--rule "<rule string>"]`.
+    - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error [--note "<what it misread>"] [--rule "<rule string>"]`.
+    - *Out of scope* (handled outside the system): `iamu triage <slug> --status dismissed --reason out_of_scope [--note "<how it is handled>"] [--rule "<rule string>"]`.
+    - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
+      `iamu triage [slug] --status dismissed [--note "<why>"] --rule "Don't report: <X>" --sweep "<keyword>"`.
+      This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, the matcher, the judge (`evaluate`) and `fix-brief` respect. The designer never reads tester guidance: a swept designer finding is dismissed, and later designer's reviews are told not to raise it again.
+    - *Duplicate* of another finding: `iamu triage <slug> --status dismissed --duplicate-of <other-slug> [--note "<note>"]` (no rule is written).
 
-- **Won't fix (accepted trade-off)** → the problem is real but the team accepts it. `iamu triage <slug> --status wont_fix --note "<the trade-off>"`. It stays out of future walks' dismissed list only as a known issue — no guidance rule is written.
+  `not_relevant`, `walker_error`, and `out_of_scope` write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to `"Don't report: <title>"`; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad, or `--no-guidance` to skip writing a rule. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."**
 
-- **Not relevant / walker got it wrong (Load-Bearing Guidance Learning)** → the finding should never have been reported. **Never infer the reason silently.** Always ask the user:
-  > "To teach future walkthroughs what not to report, why should this be dismissed?
-  > • **By design / intended behavior:** (Why this pattern is expected)
-  > • **Walker error:** (What the walker misread or did wrong)
-  > • **Out of scope:** (Non-issue for this product/flow)
-  > What specific rule should future walkers follow?"
-  
-  Once the user provides their rationale:
-  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>" --rule "<rule string>"`.
-  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>" --rule "<rule string>"`.
-  - *Project-wide sweep ("we never want X" / "X is a test harness everywhere")*: When the user's intent applies across the entire product (including designer findings or other scenarios), pass `--sweep` (or `--sweep "<keyword>"`):
-    `iamu triage [slug] --status dismissed --note "<why>" --rule "Don't report: <X>" --sweep "<keyword>"`.
-    This sweeps and dismisses every matching open persona and designer finding across all scenarios and surfaces in one command, and records a project-wide guidance rule that the walker, matcher, judge, designer, and `fix-brief` all respect.
-  - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
-
-  Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "✓ Dismissed (<reason>) — Guidance rule taught to future walks in iamu/guidance/<slug>.md: '<rule string>'."** One-word notes ("nope") degrade future runs — capture the user's specific rationale.
-
-- **Keep (no decision yet)** → rare. Use only when the reviewer genuinely needs more information. Leave `triage_status: open` and add a `triage_note` noting what you are waiting for: `"Waiting on <thing> before triage."`.
+- **Keep open (no decision yet)** → leave `triage_status: open` and optionally attach a `triage_note`: `iamu triage <slug> --status open --note "Waiting on <thing> before triage."`.
 
 Report back with the action taken:
 
@@ -213,11 +205,8 @@ Report back with the action taken:
 addressed (fix now): <finding-slug>
   Change: made handoff notes optional on /sv/handoff
 
-deferred: <finding-slug>
-  Note: revisit after Q3 mobile release
-
 dismissed (duplicate): <finding-slug>
-  Reason: duplicates frontline-worker--incident-report-overwhelm-a7b2c1
+  Duplicate of: frontline-worker--incident-report-overwhelm-a7b2c1
 
 dismissed (not_relevant): <finding-slug>
   Reason: the beta badge is intentional until launch
@@ -275,7 +264,7 @@ Triage decisions are team state: until they sync, teammates still see these find
 iamu sync --json
 ```
 
-Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `conflicts`, a teammate changed the same finding: name it and give the resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours). If it has `pending_deletes`, list them and tell the user to run `iamu sync --confirm-deletes` after checking. Never run `--keep-mine` or `--confirm-deletes` yourself — only the user decides to overwrite or delete team data.
+Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `conflicts`, a teammate changed the same finding: name it and give the resolution (`iamu pull --force <slug>` to take theirs for that finding after copying your edits aside, or `iamu sync --keep-mine` to keep yours; `--force` without a slug replaces all local files). If it has `pending_deletes`, list them and tell the user to run `iamu sync --confirm-deletes` after checking. Never run `--keep-mine` or `--confirm-deletes` yourself — only the user decides to overwrite or delete team data.
 
 Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
 
@@ -288,7 +277,7 @@ In linked-no-credentials mode, end with `Decisions are local only — iamu auth
 - **Links a terminal can open.** Terminals open only what they can see. Write web addresses in full (`https://…`), never hidden behind link text, and files as absolute paths (the project root plus the path), never relative. Name scenarios, personas and findings by slug in backticks; they need no link.
 - **Terminal-complete.** Everything the user needs to triage fits in chat. Citations, recommendations, linked steps, screenshots (as paths the agent can read if it has image support). Dashboard is nice-to-have, not required.
 - **Group by scenario, not by type.** Findings aggregate around scenarios. When reviewing, the context of "what happened in Maria's shift handoff?" matters before deciding on each finding — not seeing all severity:critical across projects.
-- **Severity-sorted within each group.** Within a scenario group, sort CRITICAL → MAJOR → MINOR → OBS. Within the same severity, show hinders/missing/incorrect before helps.
+- **Severity-sorted within each group.** Within a scenario group, sort CRITICAL → MAJOR → MINOR → NIT. Within the same severity, show hinders/missing/incorrect before helps.
 - **Screenshot paths over inline images.** Skill prints `iamu/.runs/<run>/screenshots/step-<N>.png` paths. Agents with image-capable read can open them on request.
 - **Every finding gets a decision — none disappear silently.** Fix now, design change, defer, won't fix, or explicit "waiting on X". No finding exits triage unreviewed. This discipline is load-bearing: silent skips degrade the signal the next walkthrough depends on.
 - **Bias toward small, direct fixes.** If something can be fixed in five minutes without risk, do not create a design process for it — fix it now and triage as addressed with a one-line change summary.

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

@@ -42,13 +42,13 @@ Determine the mode based on `$ARGUMENTS` and user intent:
   1. Ground in `iamu/context.yml` actors, domain, and jurisdiction.
   2. Define role, disposition, key biases, friction triggers, and domain vocabulary.
   3. Propose the persona candidate to the user (name, role, disposition, expectations).
-  4. Once confirmed, scaffold the persona into `iamu/personas/`:
-     ```bash
-     iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
-     ```
-  5. Write the persona's background narrative and test expectations as the markdown body.
-  6. Run `iamu validate --all`.
-  7. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
+   4. Once confirmed, scaffold the persona into `iamu/personas/` with its background narrative and `## Today` section passed via `--body` (or update later with `iamu set persona <slug> --body "..."`):
+      ```bash
+      iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<Background narrative and test expectations>\n\n## Today\n<How this person does the job today without the product>" --json
+      ```
+   5. Ensure the persona's markdown body includes their background narrative and test expectations, ending with a `## Today` section: how this person does the job the product is for today, without it (a paper sheet, a spreadsheet, phone calls, a colleague, another tool), and what that costs or gives them. The walker holds the product against it and the judge weighs voluntary use against it.
+   6. Run `iamu validate --all`.
+   7. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
 
 - **Fast-Path Scenario mode** (when intent, topic, an Acceptance Criterion / User Story, or a candidate from `iamu-propose` is provided or referenced from conversational context, e.g. `iamu-new "checkout friction"`, `iamu-new "AC: System must require re-auth on payout change"`, "let's do candidate 2", "draft that", "option 1"):
   - **Acceptance Criteria & User Stories:** When input contains an AC or user story:
@@ -239,9 +239,9 @@ The `--capability`, `--additional-capabilities`, `--tension`, `--narrative`, and
 
 **3. Persona** (if user picked a new persona to scaffold):
 ```bash
-iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --json
+iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --body "<Persona background narrative and test expectations>\n\n## Today\n<How this person does the job today without the product>" --json
 ```
-The `--role` and `--disposition` flags populate frontmatter directly. Leave `access` out — which product account the persona uses is decided when the scenario is staged in `iamu-run`. Write the persona's background narrative and test expectations as the markdown body.
+The `--role`, `--disposition`, and `--body` flags populate frontmatter and the markdown body directly (or you can update the body via `iamu set persona <slug> --body "..."`). Leave `access` out — which product account the persona uses is decided when the scenario is staged in `iamu-run`. End the `--body` with a `## Today` section: how this person does the job the product is for today, without it (a paper sheet, a spreadsheet, phone calls, a colleague, another tool), and what that costs or gives them. The walker holds the product against it and the judge weighs voluntary use against it.
 
 **4. Scenario** (the binding):
 ```bash