@iamu-dev/iamu 0.4.0-beta.1 → 0.6.0-beta.0

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

@@ -1,6 +1,6 @@
 ---
 name: iamu-findings
-description: Use when triaging, reviewing, listing, or resolving findings, bugs, UX friction, or issues discovered during walkthroughs, or when the user asks "what broke?", "show findings", or "review issues".
+description: Use when triaging, reviewing, listing, or resolving findings (what personas experienced and what the designer saw), bugs, friction, or issues discovered during walkthroughs, or when the user asks "what broke?", "show findings", or "review issues".
 generatedBy: __IAMU_VERSION__
 ---
 
@@ -61,20 +61,28 @@ 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`, `scenario`, `type`, `severity`, `title`, `where` (page and step), `recommendation` (the advisor's, or null) and `fix_state`. 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) and `fix_state`. One list, worst first, with both sources: say on every row who found it ("Ana found" / "the designer found (seen)"), 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`.
 
 **Fixed is not proven.** `triage_status: addressed` means a fix was applied. `iamu findings --json` adds `fix_state` to each addressed finding, derived from local runs:
 
-- `awaiting_rerun` — no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `awaiting_rerun` — a persona finding: no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `awaiting_review` — a designer finding: no designer's review of its page since the fix. A re-run's designer's review checks it, or a page check (below).
 - `verified` — a run that started after the fix saw it working (the since-last-run delta's "Resolved", backed by steps).
 - `recurred` — a run after the fix recorded it again: the fix did not hold. Reopen it (`iamu triage <slug> --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.
+A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. The eye that raised a finding confirms it: a re-run confirms the persona's findings, a designer's review the designer's; never the other way round.
+
+**Checking whether something is fixed, on request.** When the user asks in plain words ("is the pending colour fixed?", "check the approvals page"), find the findings meant and route by `source`:
+- **A designer finding:** check its page. Run `iamu design review <page> --blind` and have a fresh reviewer with a browser answer it (it is not told which findings were open: the check is blind), record it with `iamu design review-record <page> --file <answer>`, then `iamu design review-match <page> --json`; give its prompt to a fresh agent and record with `iamu design review-match-record <page> --file <answer>` (when it says `nothing_new`, record `--data '{"matches":[]}'`). Report what is still there and what was not seen again. While the result says `provisional: true`, say "not seen again (provisional)" and never "fixed": the check is not trusted yet.
+- **A persona finding:** a screenshot cannot say whether the person still gets stuck. Offer a re-run of the scenario that raised it (`iamu-run <scenario>`).
+- **A persona finding with design causes:** the re-run decides; a page check of its design cause is supporting evidence only. 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.
 
 **Directions before findings.** Run `iamu directions --json`. Directions are structural changes the advisor proposed after a walk, each absorbing several findings (sometimes across scenarios), with the people it could hurt and the scenarios to re-run. If any are `proposed` or `accepted`, show them above the tally, one line each: `◆ <title> (<size>, <status>) · absorbs <N> findings in <S> scenarios · could hurt: <scenarios or "none predicted">`. Offer them first: taking a direction fixes its findings together, which beats patching them one by one. For each the user can **take it** (`iamu directions set <slug> --status accepted`, then implement it, or hand it to planning when it is `large`), take **only the local fixes** (leave it `proposed`, triage its findings below), **defer**, or **reject** (`--status rejected`; it is never proposed again). When a taken direction is implemented, mark it `done` and offer `iamu-run` for every scenario in its `verify` list. Reach is a prediction: say "likely" and "could", never "will".
 
+**Design doc proposals.** Run `iamu design proposals --json` and note the open ones: edits the advisor, the designer (after a run, or reviewing a page) or a design review proposed to the project's design docs (a rule whose application hurt someone, or something the docs do not cover). They are decided after the findings (step 5), next to the evidence that raised them. When several open findings sit on one page, offer a design review of that page (`iamu-design`, review a surface) before fixing them one by one. *The designer's review of a run looks at the screens one run's persona saw, after every run; a designer's review of a page looks at one page live, across all its visitors, when asked.*
+
 When open findings span three or more scenarios and there are no open directions, or the user asks what to change first, offer a project synthesis: `iamu advise --project --json`, dispatch a thorough-tier subagent with `iamu/.analysis/advise_prompt.md` as its only context, and record its answer with `iamu advise-record --project --data '<json>'`. It proposes directions across every scenario.
 
 Render it as Markdown, not inside a code fence, so the tables render. Start with a one-line tally, then one block per scenario, scenarios with the worst verdict first:
@@ -88,7 +96,7 @@ Render it as Markdown, not inside a code fence, so the tables render. Start with
 |---|---|---|---|---|
 | 1 | <title> | **Critical** | <where> | <first sentence of recommendation, or — > |
 
-Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → observation; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out of the tables. Keep the "What to do" cell to one sentence: the full recommendation belongs in the finding card (step 3).
+Number findings continuously across scenarios, so "fix 3" means one finding. Sort each table worst first (critical → major → minor → nit; incorrect, hinders and missing before irrelevant). Leave strengths (`helps`) out of the tables. Keep the "What to do" cell to one sentence: the full recommendation belongs in the finding card (step 3).
 
 Ask the user how they would like to triage:
 
@@ -178,7 +186,7 @@ triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
 
 - **Queue to fix [Recommended in list-mode]** → add to the session's fix queue. Tell the user in 1 line: "✓ Queued for fix. Advancing to next finding..." and loop to the next finding. Complete the triage queue across all findings first.
 
-- **Fix immediately (leave triage now)** → the change is small, one-or-two files, and user explicitly chose to leave triage now. 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.
+- **Fix immediately (leave triage now)** → the change is small, one-or-two files, and user explicitly chose to leave triage now. Fix with the fix loop, not blind: run `iamu fix-brief <slug> --json` and follow its `loop` (before and after screenshots of the page in `shots_dir`, helped / hurt / no visible change, the strengths and design rules it lists kept intact). 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."`.
 
@@ -232,6 +240,8 @@ When all findings in the queue are triaged, present what was decided, one row pe
 | 3 | <title> | Defer | Revisit after the next run |
 | 4 | <title> | Dismissed | <reason>; guidance `<slug>` taught to future walks |
 
+**Then the proposed edits to the design docs.** For each open proposal from `iamu design proposals --json`, show its Why, the rule and file it changes, the findings it rests on, and the change as two short `text` blocks, Before then After. Ask: **accept** (`iamu design accept <slug>`: it replaces exactly the Before in the doc with the After), **edit After then accept** (change the After block in `iamu/design/proposals/<slug>.md` to the user's wording first), **reject** (`iamu design reject <slug>`), or **later**. A `stale` proposal, or an accept that stops with `before_not_found`, is offered only as edit (rewrite its Before to the doc's current text and its After to match, then accept) or reject. One marked as legacy (the earlier format) can only be rejected, or left for a later run to raise again. Never accept one on the user's behalf.
+
 If `<N> > 0` findings were queued for fix:
 - Prompt the user:
   - If interactive tool available:
@@ -244,7 +254,7 @@ If `<N> > 0` findings were queued for fix:
     Proceeding with code edits — say "done" to keep fixes open in iamu/findings/.
 
 - **Executing the queued fixes:**
-  When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace — the fix shown on its card or agreed in Discuss, not the walker's original text. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+  When Option 1 is chosen, fix each queued finding in turn with the fix loop (`iamu fix-brief <slug>`, before and after screenshots of its page, helped / hurt / no visible change) — the fix shown on its card or agreed in Discuss, not the walker's original text. Findings on the same page go together: fix them as one change to that surface. Verify once at the end (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
   Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Closed-Loop Regression Verification (1-Click):**

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

@@ -12,6 +12,8 @@ This skill resolves what scenario to run following a clear **Target Scenario Res
 2. **Active conversational context:** When `$ARGUMENTS` is empty or generic (e.g. "it", "that", "this", "run it", "walk it", "go"), and a scenario was created, modified, staged, or discussed in the active session — immediately resolve to that active scenario without prompting or re-scanning.
 3. **No argument & No active session scenario:** Check unfinished runs, then present a prioritized pickable list (reruns needing proof first, then drafts and ready-to-run).
 
+**`--no-ux`:** when `$ARGUMENTS` contains `--no-ux`, take it out before resolving the scenario and skip the designer's review (step C3) for this run only: after A, record `iamu designer-record <run-id> --skipped "--no-ux"` so the report says it was skipped. There is no project setting for it: every other run gets a designer's review.
+
 $ARGUMENTS
 
 ## Prerequisites
@@ -264,7 +266,7 @@ The result's `walker_prompt` is the walker's entire prompt (also persisted at `w
 
 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.
 
-**Subagent Capability Fencing (Superpowers Pattern):**
+**Subagent capability fencing:**
 - **Tool Whitelist:** If the host allows tool restriction, grant the walker ONLY the browser driving tools (`iamu browse` or browser MCP) and read-only inspection.
 - **Tool Blacklist:** Strictly strip file write/edit tools (`write_to_file`, `replace_file_content`, patch/edit tools, and source git commits). The walker is an observer, never a developer.
 - **Child Session Suppression:** The walker must never execute parent workflow routines (`iamu init`, `iamu triage`, `iamu new`). All steps, findings, and summaries are recorded atomically via `iamu browse step`, `iamu new-finding`, and `iamu summary`.
@@ -338,7 +340,7 @@ iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type h
 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`.
+Valid `--severity` values: `critical`, `major`, `minor`, `nit`.
 Valid `--task-impact` values (effect on the persona's task): `blocks`, `impairs`, `slows`, `neutral`, `accelerates`, `enables`. A `helps` finding is never `blocks`/`impairs`/`slows`; a problem is never `accelerates`/`enables`.
 Valid `--confidence` values: `high`, `medium`, `low` (use `low` when it may be a tooling limitation).
 
@@ -354,7 +356,7 @@ iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --questi
 
 **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.
+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; the designer's review (C3) starts right after A and runs beside them.
 
 > **CRITICAL EXECUTION RULE (Zero Host File Tools):**
 > Never invoke host edit or write tools (`write_to_file`, `create_file`, `replace_file_content`, etc.) on any files in `iamu/` (including run artifacts, steps, findings, outlines, personas, scenarios, or guidance). All files in `iamu/` must be generated and modified exclusively via `iamu` CLI commands (`iamu new`, `iamu set`, `iamu step`, `iamu new-finding`, `iamu evaluate-record`, `iamu match-record`, etc.). If an entity needs a field updated (e.g. adding a capability to an outline), run `iamu set <type> <slug> ...` instead of editing files by hand. Record subagent JSON outputs directly through the CLI using `--data '<json>'` (or pipe via stdin).
@@ -413,6 +415,22 @@ Each entry is checked on its own. Entries that come back rejected (an invented f
 
 The judge (C) and the advisor (C2) are independent, so their subagents may run in parallel, but run `evaluate-record` and `advise-record` one after the other: both rewrite finding files. On a host without subagents, run the advise prompt yourself inline and record it the same way.
 
+**C3. Designer's review.** For every run (unless `--no-ux` was given), start it as soon as A is done:
+
+```bash
+iamu designer <run-id> --json
+```
+
+If `needed` is `false` (`reason` is `blocked`, `no_screens` or `already_recorded`), skip it. Otherwise dispatch a fresh subagent that can look at images (the **thorough** model tier) with `iamu/.runs/<run-id>/designer_prompt.md` as its only context, alongside the matcher (B), the judge (C) and the advisor (C2) where the host allows. It reviews the screens the persona saw as the product's designer would: against the project's design docs when they apply to this run (`judged_against: design-docs`), else against general craft, across the whole screen. What it finds are designer findings: judgement, never the persona's experience, and never counted with the persona's findings or in the verdict.
+
+Nothing waits for it: the advisor never waits for the designer, and D and E go ahead without it. When its answer arrives, record it:
+
+```bash
+iamu designer-record <run-id> --data '<raw_designer_json>'
+```
+
+Never run two record commands at the same time: `match-record`, `evaluate-record` and `advise-record` keep their order, and `designer-record` runs between them when its answer arrives. It re-derives the report and never touches the persona's finding files. If the subagent fails or its answer is rejected, retry once, then continue without it and record `iamu designer-record <run-id> --skipped "the designer failed"`. If `designer-record` says `rederive_failed`, run the `fix` it prints. On a host without subagents, answer the prompt yourself after C2 and record with `iamu designer-record <run-id> --by-orchestrator --data '<raw_designer_json>'`; the report then says the review was not written by a separate agent. Keep the result's `proposals` for step 5.
+
 **D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including the verification delta (if a prior run exists) and `analysis.directions` (if the advisor ran). Use this for step 5 presentation.
 
 **E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
@@ -431,7 +449,7 @@ It prints the URL only if the run is on the cloud; otherwise it exits 1 and says
 
 In linked-no-credentials or local-only mode, skip E.
 
-Only after A→E (with C2) are complete, proceed to step 5.
+Only after A→E (with C2) are complete, proceed to step 5. If the designer has returned by then, record it first; if not, present without it and add the designer's review when it lands. If it lands after E, run `iamu sync --json` once more so the cloud report carries it.
 
 ### 4a. Walk methodology summary
 
@@ -473,7 +491,7 @@ For a persisting finding, put its qualifiers in brackets: the `shift` ("less sev
 |---|---|---|---|---|
 | 1 | <title> | **Major** | <where> | <first sentence or two of recommendation, or — > |
 
-Mark a finding that persists from the last run with `(persists)` after its title. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
+Mark a finding that persists from the last run with `(persists)` after its title. When the designer gave a finding's design cause (a `summary.designer.issues` entry whose `design_cause_of` is that finding's `id`), add it under the row as `↳ Design cause (designer, <basis>): <what>`. Strengths go on one line under the table: `✓ Strengths: <title>; <title>`.
 
 If `summary.directions` is non-empty:
 
@@ -485,7 +503,14 @@ If `summary.directions` is non-empty:
 
 Reach is a prediction until those scenarios run again.
 
-If `summary.observations` is non-empty, end with **Also worth knowing**: one bullet each, `Not walked: <title>` (coverage_gap) or `Risk: <title>` (feature_risk).
+If `summary.designer` is set, add the **Designer's review**: the designer's judgement of these screens, never the persona's experience. Give its count apart from the persona's ("2 designer findings"), never one total.
+- One line on what it was judged against: the design docs in `summary.designer.design_files`, or, when `judged_against` is `general-craft`, `Judged against general craft: recording the project's design docs makes this review sharper`, followed by the `hint` command `iamu designer` printed. Say so when `dispatch` is `inline` ("written by the orchestrator, less independent").
+- The rule breaks (`summary.designer.rules_broken`), one line each: `"<rule>" (<file>) on <screen>, step <n>`, then `<rules_held> rules held`.
+- The major and critical designer findings that are not a design cause (`summary.designer.issues` with no `design_cause_of`), one line each: `<id> · designer · <severity> · <basis> · <screen> · <title>`, with `breaks "<rule>"` when it breaks one; then the count of minor and nit ones in one line.
+
+If `summary.observations` is non-empty, end with **Also worth knowing** (the advisor's notes): one bullet each, `Not walked: <title>` (coverage_gap) or `Feature risk: <title>` (feature_risk).
+
+If the advise step or the designer proposed design doc edits (`design_proposals` in the advise result, `proposals` in the designer result), add one line: `Design docs: <N> proposed edits — decided after the findings`. They wait for a person; never apply them yourself.
 
 If `summary.setupNotes` is non-empty, add **Test setup** with one bullet each. These are doubts about the test, not the product (missing data, an account that cannot see enough, a date the scenario assumes). Offer the `iamu-stage` skill to fix the setup before the next run; a finding that rests on a setup doubt may not be real.
 
@@ -496,7 +521,7 @@ Do NOT prompt the user with a generic "How would you like to proceed?" multiple-
 
 - **If `summary.findings` is empty (no problems):**
   Output: "No problems found in this run." The verdict above still stands on its own: a run without findings can still answer NO.
-  Do not enter triage.
+  Do not enter finding triage for the persona; when the designer's review has major or critical designer findings, triage those (step 6 lists them the same way), then the proposed design doc edits.
 
 - **If `summary.findings` is not empty:**
   Output the Executive Scorecard above to chat FIRST, and advance IMMEDIATELY to triage on **Finding #1 of <total>** (Step 6 below) in the same turn. The user can choose to queue to fix, queue all remaining fixes (batch accept), dismiss, or discuss directly from Finding #1.
@@ -511,6 +536,8 @@ The conversation is the triage surface. Do NOT eject the user to manual CLI comm
 - **Defer** (leave `proposed`) or **reject** (`iamu directions set <slug> --status rejected`; it will not be proposed again).
 After a taken direction lands, mark it `done` and re-run the scenarios in its `verify` list, not only this one.
 
+**One list, worst first.** Triage goes through one list: every persona problem finding, and the designer findings at `major` or above that are not a design cause, ordered by severity (critical, major, minor, nit), persona before designer at equal severity. A persona finding and its design causes are one card and one decision. Number the cards across the whole list ("#3/7"). Every card opens with whose finding it is: "**Ana found:**" for a persona finding, "**The designer found (<basis>):**" for a designer finding. Severity means harm to the person for both.
+
 #### 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 a scannable format (High Visual Hierarchy):**
@@ -530,6 +557,18 @@ When the user asks to review findings one by one:
    ```
    *(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
 
+   When the persona finding has design causes, add under the problem: `**↳ Design cause** (<id>, the designer, <basis>): <what> <why>` and `breaks "<rule>"` when it breaks one. It is decided with the finding.
+
+   A designer finding's card:
+   ```markdown
+   ### Finding #<N>/<total> [<SEVERITY>] — <title> · designer
+   > **The designer found (<basis>):** on `<screen>` (Step <N>) · <breaks "<rule>" (<file>) when set>
+   > **Evidence:** <run_dir>/screenshots/step-<N>.png
+
+   **What the designer saw:** <what> <why>
+   ```
+   Never write it in the persona's voice, never quote the persona for it, and say "taste" plainly when its basis is taste.
+
    If the project is cloud-linked, include the direct link to the walkthrough in Iamu Cloud (from `iamu open <run-id> --print`).
 
    Followed immediately by the decision prompt:
@@ -579,7 +618,7 @@ When the user asks to review findings one by one:
      Record the agreed decision and advance to finding #<N+1>. Do NOT trap the user with modal dialogs after each conversational turn.
    - **Fix immediately (leave triage now)**:
      If the user explicitly chooses to drop out of triage and fix right now:
-     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>"`.
+     Fix with the fix loop, not blind: run `iamu fix-brief <slug> --json` and follow its `loop` (before and after screenshots of the page in `shots_dir`, helped / hurt / no visible change, the strengths and design rules it lists kept intact). Then record: `iamu triage <slug> --status addressed --note "<summary of fix>"`.
      Tell the user in 1 line: "✓ Applied fix. Finding #<N> marked addressed."
    - **Next finding (keep open / defer)**:
      Leave open (or set `triage_status: deferred` with note) and advance to finding #<N+1>.
@@ -589,6 +628,9 @@ When the user asks to review findings one by one:
    ```text
    Triage Complete: <K> queued for fix, <D> dismissed, <O> kept open/deferred.
    ```
+   A designer finding is decided with the same choices: **queue to fix** (fixed from `iamu fix-brief <run-id>#D<n> --json` and its `loop`; the next designer's review of that screen shows whether it held), **dismiss** (`iamu designer-dismiss <run-id> D<n> --reason "<why>"`: later reviews do not raise it again unless it gets worse, and no rule is taught to the walker), or **later** (record nothing; it stays in the report). Minor and nit designer findings stay in the report and are not offered.
+
+   **Then the proposed edits to the design docs**, before any fixes: decide each open one exactly as the `iamu-findings` skill describes under "Then the proposed edits to the design docs" (Why, the rule and file, the findings, Before → After; accept, edit After then accept, reject, or later). Never accept one on the user's behalf.
    If `<K> > 0` (findings are queued for fix):
    - Prompt the user to execute the batch:
      - If interactive tool available:
@@ -602,7 +644,7 @@ When the user asks to review findings one by one:
        Proceeding with code fixes — say "re-run first" or "done for now" to adjust.
 
    - **Executing the queued fixes:**
-     When Option 1 is chosen, apply code edits for each queued finding sequentially in the workspace. Verify the changes once (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
+     When Option 1 is chosen, fix each queued finding in turn with the fix loop (`iamu fix-brief <slug>`, before and after screenshots of its page, helped / hurt / no visible change); findings on the same page go together as one change. Queued designer findings are fixed the same way from `iamu fix-brief <run-id>#D<n>`; mark each by the `finding.slug` its brief gives (a later designer's review of that screen confirms it, not the re-run). Verify once at the end (run test/typecheck suite). Update each finding with `iamu triage <slug> --status addressed --note "<summary of fix>"`.
      Tell the user: "✓ Applied fixes for <K> findings. All marked addressed."
 
    - Run `iamu validate --all`.

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

@@ -14,6 +14,7 @@ What this skill does, end to end:
 - **Understand** — read the repo automatically to detect dev server, mock fixtures, external boundaries, domain stakes, and user roles.
 - **Step 1: Safety & Testability Fence** — agree on the sandbox boundaries (`iamu/testability.md`) so the autonomous browser agent never leaks data or hits real external services.
 - **Step 2: Project Domain & Description** — verify domain context and project description (`iamu/context.yml`) to ground UX evaluations.
+- **Design docs (skippable)** — record where the project's own design docs are (`iamu/design/sources.json`).
 - **Step 3: Co-Design First Journey** — co-create a high-friction scenario, verify auth preconditions (`personas/`, `outlines/`, `scenarios/`), and validate.
 - **Next Action** — copy-pasteable command to launch your first walkthrough.
 - **Cloud (optional)** — link to Iamu Cloud if you want to share findings with your team.
@@ -161,6 +162,10 @@ Explain the purpose of project context: traditional tests only assert button cli
 
 Present the discovered domain and project description. Do NOT introduce or ask the user to approve personas or roles at this stage — personas are cast later when designing specific test journeys.
 
+**Describe the product, not the environment you explored.** Persona drafting and the advisor read these fields and the description as the truth about the product. Write them as the product its people use in their real work. Leave out everything about how this copy runs, because Step 1 already recorded it in `testability.md`:
+- **Data and build:** seeded, mocked, fixture, sample or fake data; demo, prototype or staging status; where data is stored; frontend or backend architecture; dev servers.
+- **Seed numbers:** headcounts, named teams, stores or sites, and record counts taken from seed or fixture files describe the test data, not the customers. Say who the product is for in general terms ("small and mid-sized companies"). Rules and policies the code enforces (a notice period, an approval threshold) are product behaviour; keep them.
+
 **Dual-Surface Prompting (Sequencing Rule):**
 You MUST output the domain context and project description to the chat stream FIRST. In the SAME turn, invoke `ask_question` with the complete substantive project description embedded in the `question` argument so the reviewer can read the full text directly within the dialog modal:
 
@@ -219,7 +224,7 @@ Persist the domain context using `iamu set context` (never invoke host file crea
 iamu set context \
   --domain "<domain>" \
   [--industry "<industry>"] \
-  --body "<The substantive 1–2 paragraph project description and core user workflows>" \
+  --body "<The 1-paragraph project description, as confirmed>" \
   --json
 ```
 
@@ -228,6 +233,18 @@ iamu set context \
 
 ---
 
+### 4b. Optional: design docs (quick, skippable)
+
+The team's design docs are part of the product's context, like the domain. Iamu reads them wherever they are and never edits them on its own. Run `iamu design detect --json`.
+
+- **Found docs** (a `DESIGN.md` in any format, design-system, brand, voice or interaction docs, design sections of `CLAUDE.md` or `AGENTS.md` shown as `CLAUDE.md#<heading>`, a `PRODUCT.md`, token files, a component library): list them once, one line each (kind, path). Show a candidate with a `note` (tokens in a template, export or fixture folder) with its note, unticked. Ask once whether to record them; the user may drop some or add others. On yes, `iamu design sources <paths…>` (in a monorepo, `--applies-to` with the URL prefix or the app's folder each doc covers).
+- **A legacy `iamu/design.md`** (`iamu design status --json` shows `legacy.doc` and no `legacy.migrated_at`): fold it into the same single question. Run `iamu design migrate --json` first, and offer three answers next to the files: **move it** to a plain `DESIGN.md` the team owns (`iamu design migrate --move-to DESIGN.md --apply`), **keep** `iamu/design.md` as it is (`iamu design migrate --apply`, which records the choice so it is not offered again), or **not now** (run nothing; it is offered again next time). Only an explicit "keep" runs `--apply` without a move.
+- **Nothing found:** say so in one line and continue. Walks run without design docs.
+
+Do not assess or draft design docs here. Never block setup on this step.
+
+---
+
 ### 5. Step 3/3: Co-Design Your First Test Journey (`personas/`, `outlines/`, `scenarios/`)
 
 Explain the journey model: an Iamu test binds a **Persona** (with habits, pressures, and impatience) to a **Situation** (a realistic high-stakes problem) with an **Evaluation Checkpoint** (a concrete binary question for the AI judge).
@@ -325,6 +342,7 @@ Render the output:
   iamu/
   ├── testability.md       [safety fence active: <target_url>]
   ├── context.yml          [domain: <domain>]
+  ├── design/sources.json  [<N> design docs]   (only when recorded)
   ├── personas/
   │   └── <persona-slug>.md
   ├── outlines/
@@ -340,6 +358,7 @@ Next step:
 Other commands when you're ready:
 • iamu-new      Draft a scenario for a different product flow
 • iamu-propose  Brainstorm high-risk workflows and blind spots
+• iamu-design   Record the project's design docs, review a page, decide proposed edits
 • iamu doctor   Diagnose test environment and target health
 <If cloud_linked: true>
 • iamu sync     Sync completed runs and findings to Iamu Cloud

package/dist/templates.d.ts

@@ -8,3 +8,16 @@
 export declare function getTemplatesRoot(): string;
 export declare function getTemplateDir(subdir: "skills" | "prompts"): string;
 export declare function getTemplateFile(subdir: "skills" | "prompts", filename: string): string;
+/** Prompt templates `iamu init` installs and `iamu update` refreshes in `iamu/.prompts/`. */
+export declare const PROMPT_FILES: readonly ["walk.md", "persona.md", "outline.md", "combine.md", "complete.md", "evaluate.md", "advise.md", "design-draft.md", "design-review.md", "design-review-match.md", "designer.md"];
+/**
+ * A prompt as the project has it: its `iamu/.prompts/<name>` copy (which
+ * a team may tune), else the bundled template.
+ */
+export declare function readInstalledPrompt(projectRoot: string, name: (typeof PROMPT_FILES)[number]): string;
+/**
+ * A warning when the project's `iamu/.prompts/<name>` differs from the
+ * bundled template: answers written from an older method may cite rules
+ * by id or propose in an old format. Null when it matches or is absent.
+ */
+export declare function installedPromptWarning(projectRoot: string, name: (typeof PROMPT_FILES)[number]): string | null;

package/dist/ui/html-report.d.ts

@@ -1,4 +1,4 @@
-import { type CheckOutcome, type RunChecks } from "@iamu-dev/local-store";
+import { type CheckOutcome, type RunChecks, type CanonicalAnalysis, type CanonicalDesigner } from "@iamu-dev/local-store";
 export interface HtmlReportHighlight {
     targetBox: {
         x: number;
@@ -38,6 +38,10 @@ export interface HtmlReportFinding {
     title: string;
     type: string;
     severity?: string | null;
+    /** What the walker filed, when the advisor's check changed the severity. */
+    filedSeverity?: string | null;
+    /** Why the advisor changed it. */
+    severityWhy?: string | null;
     uiFact?: string | null;
     consequence?: string | null;
     recommendation?: string | null;
@@ -102,6 +106,10 @@ export interface HtmlReportData {
         }>;
         directions: string[];
     } | null;
+    /** The designer's review; never counted with the persona's findings. */
+    designer?: CanonicalDesigner | null;
+    /** The advisor's directions and notes, when the run was advised. */
+    analysis?: CanonicalAnalysis | null;
 }
 export declare function generateHtmlReport(data: HtmlReportData): string;
 /**

package/dist/ui/report-view.d.ts

@@ -1,9 +1,12 @@
+import { type CanonicalDesigner } from "@iamu-dev/local-store";
 export type VerdictLabel = "YES" | "PARTIAL" | "NO" | "PENDING" | "BLOCKED";
 export interface RunFindingRow {
     id: string;
     /** Finding file slug, for `iamu triage <slug>`; null when the file is gone. */
     slug: string | null;
     severity: string | null;
+    /** What the walker filed, when the advisor's check changed the severity. */
+    filedSeverity?: string | null;
     type: string;
     title: string;
     where: string | null;
@@ -18,6 +21,8 @@ export interface RunView {
     situation: string;
     completedAt: string | null;
     steps: number;
+    /** How the walk ended (reached the goal, or stopped and why); null when blocked. */
+    ending?: string | null;
     targetUrl: string | null;
     /** Cloud link, or a note that the run is not synced; null when not linked. */
     cloud: string | null;
@@ -69,6 +74,8 @@ export interface RunView {
     } | null;
     /** The walker's doubts about the test setup. */
     setupNotes: string[];
+    /** The designer's review; null or absent without one. Never counted with findings. */
+    designer?: CanonicalDesigner | null;
 }
 export interface OverviewRun {
     completedAt: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.4.0-beta.1",
+  "version": "0.6.0-beta.0",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,8 +58,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
-    "@iamu-dev/local-store": "0.1.0",
     "@iamu-dev/protocol": "0.1.0",
+    "@iamu-dev/local-store": "0.1.0",
     "@iamu/tsconfig": "0.1.0"
   },
   "scripts": {
@@ -68,8 +68,18 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "eval:walkthroughs": "vitest run --config vitest.benchmark.config.ts",
-    "eval:gemini": "node .eval-dist/gemini-eval-cli.js",
+    "eval:walkthroughs": "node ../../scripts/paid-eval-guard.mjs && vitest run --config vitest.benchmark.config.ts",
+    "eval:gemini": "node ../../scripts/paid-eval-guard.mjs && node .eval-dist/gemini-eval-cli.js",
+    "eval:setup-context": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/setup-context.yaml --no-cache --repeat 3",
+    "eval:design-draft": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/design-draft.yaml --no-cache --repeat 2",
+    "eval:walker-severity": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/walker-severity.yaml --no-cache --repeat 3",
+    "eval:design-guide-apply": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/design-guide-apply.yaml --no-cache --repeat 3",
+    "eval:advisor-check": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/advisor-check.yaml --no-cache --repeat 2",
+    "eval:ux-judge": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge.yaml --no-cache --repeat 10",
+    "eval:ux-judge-heldout": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-heldout.yaml --no-cache --repeat 5",
+    "eval:ux-judge-counter": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-counter.yaml --no-cache --repeat 5",
+    "eval:ux-judge-ablations": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/ux-judge-ablations.yaml --no-cache --repeat 5",
+    "eval:designer-check": "node ../../scripts/paid-eval-guard.mjs && npx -y promptfoo@0.124.1 eval -c evals/designer-check.yaml --no-cache --repeat 10",
     "pack:dry-run": "npm pack --dry-run"
   }
 }