@iamu-dev/iamu 0.4.0-beta.0 → 0.5.0-beta.0

package/dist/templates/prompts/advise.md

@@ -28,7 +28,7 @@ Work in this order. Do not skip ahead to writing fixes.
    - Is the rule real? Trace a regulatory claim to its source and its weight (hard requirement, process model, best practice). Never block work over a best practice.
    Prefer removing, hiding by role, deferring or leaving to people over adding. When you add something, say what it replaces or why nothing could.
 
-5. **Protect what works.** The panorama lists `strengths`: things the product does that people would miss if they were gone. A change must not remove or bury them; if it would, say so in the reach.
+5. **Protect what works, and follow the design rules.** The panorama lists `strengths`: things the product does that people would miss if they were gone. A change must not remove or bury them; if it would, say so in the reach. When `panorama.design` is set, the product has design rules (`design.doc`, and the files in `design.sources`): read them, and make your recommendations follow them. A rule marked `evidence` is backed by earlier walks; one marked `intent` is a decision nobody has tested yet.
 
 6. **Look at how the leading systems in this domain do it.** Use the project's domain (see Context). If you can search the web, use it to check how two or three leading products handle this moment today rather than relying on memory, and describe only what you found or know well. Ask how the products that handle this moment best, for this kind of person, solve it, and describe the pattern as behaviour the person would see ("the dates turn amber and say a teammate is already away that week, before they submit"). Scale it to this product's real scope: what a team of this size, for these users, would build. Not the enterprise suite's full surface. A brand may be named only next to the mechanism, never instead of it.
 
@@ -50,7 +50,9 @@ Work in this order. Do not skip ahead to writing fixes.
 
 13. **Question a feature's premise when it carries real risk.** Some features are risky as a premise, not only in their execution: processing health or other sensitive personal data, monitoring employees, automated decisions about people, dark patterns. If a feature in this product has that kind of legal, privacy or trust risk in this domain and country, say so as a `feature_risk` observation: what the risk is and what a safer form of the feature would be. Do not drop the feature from your advice on your own.
 
-14. **Decline rather than guess.** If a finding is not actionable from what you know, leave it out.
+14. **Propose design rule edits only from evidence.** When the design rules exist, you may propose the edits the evidence forces (three at most; fold related ones) in `design_proposals`: `back` a rule a strength or a finding shows working (cite it), `challenge` a rule whose application is what failed this person (the caveat it keeps small is the one they missed), or a `new` rule when two or more findings share a kind of problem no rule covers. Never propose an edit for taste. `design.proposals` lists edits already proposed: reuse an open one's slug, and never re-propose a rejected one. A person decides each one.
+
+15. **Decline rather than guess.** If a finding is not actionable from what you know, leave it out.
 
 ## Writing
 
@@ -100,12 +102,25 @@ For a run:
       "detail": "What is missing or risky, and why it matters here",
       "suggested_scenario": "Who, in what situation, starting where (coverage gaps) or null"
     }
+  ],
+  "design_proposals": [
+    {
+      "slug": "kebab-case",
+      "kind": "back | challenge | new",
+      "rule_id": "the rule (back, challenge) or null",
+      "layer": "people | look | behaviour | build (new) or null",
+      "title": "Short title (for new: the rule as a statement)",
+      "test": "For new: how to check it, else null",
+      "why": "What the evidence shows",
+      "proposed": "For challenge: better wording; for new: the rule's prose; else null",
+      "evidence": ["<ref, e.g. F3 or S2>"]
+    }
   ]
 }
 ```
 
 `observations` are at most five, never absorb findings and are never treated as evidence.
 
-For a project synthesis (the bundle says `"mode": "project"`), answer with `directions` and `observations` only: `{ "directions": [ … ], "observations": [ … ] }`. Work across every scenario: look for the causes that keep showing up in different people's findings, and propose the directions that would absorb the most of them, within this product's scope. The bundle carries every unsettled problem: `open` ones, and `addressed` ones that were patched (their `existing_suggestion` is the patch) but not yet verified by a re-run. Read `latest_verdicts`: a scenario that still fails its human test after many of its findings were patched is the clearest sign that the patches treated symptoms and the cause is structural. Say so in the direction's `problem` when it applies.
+For a project synthesis (the bundle says `"mode": "project"`), answer with `directions`, `observations` and, when the design rules exist, `design_proposals`: `{ "directions": [ … ], "observations": [ … ], "design_proposals": [ … ] }`. Work across every scenario: look for the causes that keep showing up in different people's findings, and propose the directions that would absorb the most of them, within this product's scope. The bundle carries every unsettled problem: `open` ones, and `addressed` ones that were patched (their `existing_suggestion` is the patch) but not yet verified by a re-run. Read `latest_verdicts`: a scenario that still fails its human test after many of its findings were patched is the clearest sign that the patches treated symptoms and the cause is structural. Say so in the direction's `problem` when it applies.
 
-Every `finding_id` and `absorbs` entry must be a finding `ref` from the bundle (`F1`, `F2`, …), copied exactly. Every `scenario` and `verify` entry must be a scenario slug from the panorama. Every `builds_on` path must exist and contain its symbol. Entries that break these rules are dropped one by one (an unknown absorbed id is removed from its direction) and the rest are kept.
+Every `finding_id` and `absorbs` entry must be a finding `ref` from the bundle (`F1`, `F2`, …), copied exactly; design proposal `evidence` may also cite strengths (`S1`, `S2`, …). Every `scenario` and `verify` entry must be a scenario slug from the panorama. Every `builds_on` path must exist and contain its symbol. Entries that break these rules are dropped one by one (an unknown absorbed id is removed from its direction) and the rest are kept.

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

@@ -0,0 +1,66 @@
+# Draft the design rules
+
+You write the product's design document: the rules everyone who changes the product works to, people and agents alike. Design is led by intent and refined by evidence. You are writing the intent: what this product should be like to use and to look at, for the people it is built for. Later walks will back some rules and challenge others, so every rule must be checkable against what a person does.
+
+You have the bundle below: what the product is and for whom (`context`, `people`, `situations`), what the project already has (`sources`: design docs, tokens, components), and the team's answers to the intent questions (`intent`). Source excerpts are cut short; open the full file at `project_root` + `path` before you rely on it. Quote nothing you have not read.
+
+## How to work
+
+1. **Start from the people, by name.** For each person in `people`, write a short paragraph: where they are when they use the product, what pressure they are under, how often they come, what they know and do not know, and what they fear getting wrong. The moment matters more than the demographics: "standing in a portakabin with cold hands, fifteen minutes before the crew arrives" tells a designer more than "construction worker, 57".
+2. **Turn intent into principles.** Each principle is a decision the team would defend, with the reason it matters to these people: "Nobody should feel stupid", "Show me where I am and what to do next", "Facts over forecasts". Not platitudes everyone agrees with ("be user-friendly"). Use the team's answers; where an answer is empty, derive from the people and say so in the prose.
+3. **Write each Test as one of these people in one of the `situations`.** "Can <person>, <condition>, do <task> without <failure>?" A test tied to a person and a situation is what lets later walks back the rule or show it failing.
+4. **Name the failure.** Under each principle, an `**Anti-pattern:**` paragraph names how products break it and tells, in two or three sentences, how it happens (the developer who knows every field and shows them all at once).
+5. **In practice, in the product's words.** Bullets that use the product's own labels and copy: good versus bad ("'Vad hände?' not 'Händelsebeskrivning'").
+6. **Respect what the team already wrote.** When `sources` hold the team's own rules (a design language, interaction principles), restate them faithfully as rules in this format, close to their wording, with a `From: <path>#<section>` line under the heading. Add nothing the sources and the intent answers do not support. Do not invent a visual identity the answers and the code do not support either.
+7. **Describe the look the product has, then where it should go.** Read the tokens and components. Keep what is coherent; name what the team's answers say should change.
+8. **Point at real components.** The Build layer names the components and tokens to use, by path, not copied code. Copied specs rot.
+9. **Make it as long as it needs to be, no longer.** Long enough that a reviewer could apply each principle to a screen they have never seen.
+
+## Format
+
+Markdown with exactly these four layer headings, spelled as shown, in this order. Rule ids are numbered per layer: P (People & principles), L (Look), I (Behaviour), B (Build). Under each rule heading, the field lines come first, one per line: `Source: intent` (always, for a drafted rule), `Test: …`, and `From: …` when the rule restates a source. Prose follows after a blank line. Headings inside a rule's prose are not allowed; use bold labels.
+
+```markdown
+# Design
+
+<Two or three sentences: what this product should feel like, for whom.>
+
+## People & principles
+
+<A short paragraph per person, by name: the moment they use it, the pressure, how often, what they fear.>
+
+### P1 <Principle as a short statement>
+Source: intent
+Test: Can <person>, <condition>, <task> without <failure>?
+
+<Why it matters to these people.>
+
+**Anti-pattern:** <How products break it, and how it happens.>
+
+**In practice:**
+- <In the product's own words: good, not bad.>
+
+## Look
+
+### L1 <Rule>
+Source: intent
+Test: <What to check on a screen, or what a person must be able to do>
+
+## Behaviour
+
+### I1 <Rule>
+Source: intent
+Test: <…>
+
+## Build
+
+### B1 <Rule>
+Source: intent
+Test: <…>
+
+<Which components and tokens to use, by path.>
+```
+
+## Answer
+
+Reply with the Markdown document only, starting with `# Design`. No frontmatter, no code fence around it.

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

@@ -0,0 +1,67 @@
+# Design review of one surface
+
+You review one surface of the product: a page, its states, and the flows that pass through it. You are a designer, not a persona. Personas have walked this surface; their evidence is in the bundle. Your job is to judge the surface against the product's own design rules and against what its visitors needed, and to say what should change and what must stay.
+
+## Before you judge
+
+1. **Read the design rules.** `design.doc` and every path in `design.sources` (relative to `project_root`). The project's own rules come first, then platform conventions and accessibility (WCAG), then general heuristics. If the project has no rules, say so in the summary and judge against general principles. `design.proposals` lists edits already proposed: reuse a slug instead of proposing the same edit again, and never re-propose a rejected one.
+2. **Look at the surface yourself.** Open `target_url` + each path in `paths` in the browser. Sign in and stay inside the limits that `testability` (a file) describes. Use each visitor's `viewport` when it is set. Do not stop at the landing state: open one menu, one filter, one dialog, one error or empty state. Save your screenshots under `project_root/iamu/.analysis/design/<surface>/` and read each one back; measure in the DOM when your eyes are unsure (overflow, alignment, contrast). Compare with the visitors' screenshots in the bundle.
+3. **Read the evidence.** Who comes here (`visitors`) and what they said on this surface, and who never does (`never_here`); what hurts (`problems`, `F` refs, with each person's `need` and the full recommendation); what works (`strengths`, `S` refs, which a change must not break); what was already tried here (`fix_history`: a page with many fixes is accreting, which is itself a design problem); what not to raise (`dismissed`, `guidance`).
+4. **Read what came before.** When `previous_review` is set, read it and say which of its changes landed and whether they held. When an open direction in `directions` covers this surface, judge your changes against it rather than proposing a competing one.
+
+## How to judge
+
+- **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, observed or taste, always labelled.** `evidence`: a visitor's walk shows it; cite the refs (`F3`). `observed`: 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 doc, give its `rule_id`.
+- **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, the evidence, why, and a better wording. 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.
+- **Be specific.** "The approve button and the reject link share one grey; the reject reads as disabled", not "improve hierarchy". Do not manufacture issues: a clean surface is a valid answer.
+
+Severity: `critical` (broken, unreachable, unreadable), `major` (a visitor's need is not met, or the surface is clearly inconsistent), `minor` (polish), `nit` (preference).
+
+## Answer
+
+Reply with one JSON object and nothing else:
+
+```json
+{
+  "summary": "What this surface is for, for whom, and how well it serves them (two to four sentences).",
+  "issues": [
+    {
+      "title": "Short title",
+      "severity": "critical | major | minor | nit",
+      "basis": "evidence | observed | taste",
+      "where": "/path · element or state",
+      "what": "What is wrong, specifically",
+      "why": "Why it matters to the visitors",
+      "rule_id": "L2 or null",
+      "evidence": ["F3"],
+      "screenshot": "absolute path of your screenshot, or null"
+    }
+  ],
+  "brief": {
+    "keep": ["What works and must survive any change, citing a strength (S1) or marked (taste)"],
+    "change": [{ "what": "The change, as what a visitor would see", "serves": ["<scenario slug>"], "rule_ids": ["P1"] }],
+    "open_questions": ["Decisions for the team"]
+  },
+  "conflicts": [
+    { "rule_id": "L3", "why": "How following the rule failed a visitor", "proposed": "Better wording, or null", "evidence": ["F2"] }
+  ],
+  "design_proposals": [
+    {
+      "slug": "kebab-case",
+      "kind": "back | new",
+      "rule_id": "for back: the rule the evidence supports",
+      "layer": "for new: people | look | behaviour | build",
+      "title": "For new: the rule as a short statement (optional for back)",
+      "test": "For new: how to check it",
+      "why": "What the evidence shows",
+      "proposed": "For new: the rule's prose",
+      "evidence": ["F1", "F4"]
+    }
+  ]
+}
+```
+
+Propose a design rule edit only when the evidence forces it: `back` when a strength or a fix that held shows a rule working; `new` when the same kind of problem shows up for two or more findings and no rule covers it. Fold related ideas into one proposal; three is the most a review records. Every evidence entry must be a ref from the bundle (`F` or `S`).

package/dist/templates/prompts/walk.md

@@ -56,7 +56,7 @@ Not every lens produces a finding at every screen. But you must consciously chec
 - **observation** — An enhancement opportunity. Not friction, but a missed chance to help.
 
 Finding type pairing:
-- `helps` → always observation severity. Record sparingly — only when the product actively supports the persona in a way that would be missed if removed.
+- `helps` → always observation severity. Record each one you meet: something the product does that actively supports the persona and would be missed if removed. Not baseline competence ("the button is easy to find"). These tell whoever fixes the problems what to protect.
 - `hinders` → critical, major, or minor.
 - `missing` → critical, major, or minor.
 - `incorrect` → critical or major only.
@@ -197,10 +197,11 @@ Leave `triage_status` alone; triage is not the walker's job.
 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"
+iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --question "Question for the team" --setup-note "Doubt about the test setup"
 ```
 
-- `--worked` — Things the system did well for this persona. Important to preserve.
-- `--question` — Questions that arose that need discussion.
+- `--worked` — What worked for this persona, one point each: the screen or moment and what it did for them ("The confirmation names who is notified, so I knew I was done"). Include the strengths you recorded and anything else that made the task easier. Usually three to six points.
+- `--question` — Questions for the product team: decisions the walk raised that the product does not settle and that you could not settle as the persona ("Should a reporter see the investigator's checklist at all?", "Is the 14-day notice rule enforced or only advised?"). Not doubts about the test itself.
+- `--setup-note` — Doubts about the test setup, not the product: data that seemed missing or unrealistic, an account that could not see what the situation needs, a date the scenario assumes ("No absences are recorded for summer 2027, so 'nobody is away' may only mean no data"). These go to whoever stages the scenario.
 
 Then return your final summary to the orchestrating agent so it can run `iamu complete` and the evaluation stage.

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

@@ -0,0 +1,97 @@
+---
+name: iamu-design
+description: Use when setting up or updating a product's design rules, reviewing the design of a page (interaction, layout, look and feel), deciding proposed edits to the design rules, or fixing a finding with a visual check.
+generatedBy: __IAMU_VERSION__
+---
+
+Help the product's design: its interaction design at the level of one control and of a whole flow, and its look and feel. Design is led by intent and refined by evidence. The team decides what the product should be like; persona walks show where that works and where it hurts someone.
+
+Personas experience; they do not design. Their walks are evidence. Design decisions come from the rules the team writes and from a designer's review of each surface.
+
+$ARGUMENTS
+
+## 0. Where things stand
+
+Run `iamu design status --json`. It says whether `iamu/design.md` exists, where the project's own design material lives (`sources`), how many rules are `intent` (a decision not yet tested), `evidence` (persona walks back it) or `challenged` (evidence says it hurts someone), and which proposed edits are open.
+
+Pick the mode from the user's words, or from the status when they asked generally:
+
+- no rules and no sources → **A. Set up the rules**;
+- "review this page / the request form / this finding's page / this direction" → **B. Review a surface**;
+- open proposals, or "what should change in our design rules" → **C. Decide proposed edits**;
+- "fix this finding" → **D. The fix loop**.
+
+## A. Set up the rules
+
+### A1. Record what the project already has
+
+Run `iamu design detect --json`. It finds design docs (`DESIGN.md`, `PRODUCT.md`, design-language and interaction docs), tokens and component libraries.
+
+If it finds any, show them as a short list (kind, path, why) and ask which to record. Record the chosen ones with `iamu design sources <path…>` (it adds to what is recorded). These stay the team's documents.
+
+When the sources already hold real rules (principles, a visual language, interaction rules), restate them as rules with ids so reviews and proposals can name them: run **A2** without the intent questions. The writer restates the team's rules faithfully, each with a `From: <path>#<section>` line, and adds nothing else. Without this step, a review's conflict with the team's own rules cannot be recorded.
+
+### A2. Draft rules from intent
+
+When the project has no written rules (tokens and components alone are not rules), offer to draft them now. It takes a few minutes and needs no walks: design is led by intent.
+
+1. Run `iamu design draft --json`, then read the file at `prompt_file_abs`: the bundle is in it (the product's context, its people, its situations, what the code already establishes). Read the `sources` it lists in full.
+2. Ask the five intent questions, one at a time, each with a suggested answer you derive from the bundle (the domain, who the people are, what the tokens and components already say). The user accepts, edits or skips each:
+   - What should using the product feel like, and for whom?
+   - Products whose look or way of working you want to be close to.
+   - Products, patterns or a look you never want.
+   - How dense and how plain-spoken, and does it differ by role?
+   - What must never happen to a person using it?
+3. Run `iamu design draft --answers '<json with keys feel, aim_for, avoid, density, never>' --json`. Dispatch a subagent (thorough tier) with the prompt file `prompt_file_abs` as its only context. It answers with the Markdown doc.
+4. Write the answer to `answer_file_abs` (from the draft result) and record it: `iamu design record --file <answer_file_abs>`. If it reports problems (a rule under an unknown heading, a missing `Source:` or `Test:`, wrong numbering), send the errors back to the writer once and record again.
+5. Show the result: the opening statement, then one line per rule (`P1 Nobody should feel stupid · intent`), grouped by layer. Every rule is `intent` until walks back or challenge it.
+
+### A3. Draft from evidence instead
+
+When the project already has runs, the drafter can still start from intent; walks then refine it through proposals (C). Do not wait for many runs before writing rules.
+
+### A4. Point agents at the rules
+
+Offer `iamu design link-agents` (adds a short block to `CLAUDE.md`; `--file AGENTS.md` for other agents). Only with the user's yes.
+
+## B. Review a surface
+
+A surface is a page with its states and the flows through it. Review a surface, not a single finding: a page that collected eight separate fixes needs to be seen whole.
+
+1. Run `iamu design review <target> --json`. The target is a path (`/request`), a finding (its page), or a direction slug (the pages its findings are on). It writes a prompt with the surface's dossier: who passes through and what they said there, open problems with each person's need, strengths, fixes already tried and whether they held, what was dismissed, and the design rules.
+2. Dispatch a subagent (thorough tier) **with browser access** and the prompt file (`prompt_file_abs`) as its only context. It opens `target_url` + the path, signs in as the testability notes say, opens menus and states, compares with the walks' screenshots, and answers with JSON.
+3. Write the answer to `answer_file_abs` (from the review result) and record it: `iamu design review-record <target> --file <answer_file_abs>`. Show anything it reports as `rejected` or in `warnings` (a dropped proposal, an unknown rule): never let it disappear silently.
+4. Present, in this order:
+   - the summary (what the surface is for, for whom, how well it serves them);
+   - issues as a table: severity · title · evidence, observed or taste · where · rule. Taste is labelled as taste, never mixed with evidence;
+   - **Keep** and **Change** from the brief, with whom each change serves;
+   - conflicts between a rule and a person's need, and proposed rule edits (they are now in `iamu design proposals`).
+5. Offer the fix loop (D) for the changes, starting with the one that serves the most people.
+
+The review file is `iamu/design/reviews/<surface>.md`. Its issues do not count toward any scenario's verdict.
+
+## C. Decide proposed edits
+
+Run `iamu design proposals --json`. For each open proposal, show: what it does (back rule P1, challenge L3, new behaviour rule), why (what the evidence shows), and the findings it rests on. Ask: accept, reject, or later.
+
+- `iamu design accept <slug>` applies it to `iamu/design.md`: a backed rule becomes `evidence`, a challenged rule is marked `challenged` with the reason and a proposed wording, a new rule is added as `evidence`.
+- `iamu design reject <slug>`: it is not proposed again.
+
+Accepting a **challenge** marks the rule `challenged`, with the reason and the proposed wording; the rule stays in force until a person rewrites it. Right after accepting one, show the proposed wording and offer to apply it now: edit the rule in `iamu/design.md` (new wording and test, `Source: intent`, remove the `Challenged:` and `Proposed:` lines), then record it with `iamu design record --file <project root>/iamu/design.md`.
+
+## D. The fix loop
+
+Fix by looking, not by hoping. For one finding:
+
+1. `iamu fix-brief <finding> --json` (a slug, id, or id prefix). It gives the **before** (page, step and screenshot where the persona hit it), what they **needed**, the full recommendation, the design rules tied to this finding with their tests, what the last design review said about it, the strengths on the same page that must keep working, other open problems there, fixes already tried there, the direction it belongs to, where to save screenshots (`shots_dir`), and the **loop** itself.
+2. Follow `loop` step by step. Save before and after screenshots in `shots_dir` and show their absolute paths when you report.
+3. If the change that meets the need breaks a design rule, stop and report it (the rule, the need, both screenshots) and propose a challenge: never ship either side silently.
+4. If fix-brief says the finding has no known page, take the page from the finding's step and still screenshot it before you edit.
+
+## Guidelines
+
+- **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.
+- **The project's rules come first,** then platform conventions and accessibility, then general craft. Never invent a style the team has not chosen.
+- **Evidence and taste stay labelled.** Both are useful; only evidence moves a rule.
+- **A rule that hurts someone is reported, not silently broken or silently followed.** A person decides.
+- **Prefer removing, merging and hiding by role to adding.**

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

@@ -75,6 +75,8 @@ A run that simply did not come across a finding proves nothing — never call a
 
 **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 rule proposals.** Run `iamu design proposals --json`. Open ones are edits the advisor or a design review proposed to the design rules (back a rule, challenge one that hurts a persona, add one for a recurring problem). Show them after the directions, one line each, and offer to decide them (accept applies the edit, reject is final). 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.
+
 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:
@@ -125,7 +127,7 @@ Format the visible finding in chat:
 ```markdown
 ### Finding #<N>/<total> [<SEVERITY>] — <title>
 > **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
-> **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+> **Evidence:** <project root>/iamu/.runs/<run>/screenshots/step-<N>.png · Cloud: <full https URL from iamu open <run-id> --print>
 
 **❌ Problem:**
 <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
@@ -178,7 +180,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."`.
 
@@ -223,15 +225,14 @@ dismissed (not_relevant): <finding-slug>
 
 If the user is in list-mode iteration (picked "walk through them", "all critical", or a scenario group), loop to step 3 for the next finding in the queue.
 
-When all findings in the queue are triaged, present the summary:
+When all findings in the queue are triaged, present what was decided, one row per finding, as a Markdown table (not in a code fence). Every finding in the queue gets a row, so none silently disappears:
 
-```text
-Triage complete.
-  Queued for fix: <N>
-  Dismissed: <N>
-  Rescoped (design change / defer): <N>
-  Kept open: <N>
-```
+| # | Finding | Decision | Action |
+|---|---|---|---|
+| 1 | <title> | Fix now | <what will change, or "Done" once applied> |
+| 2 | <title> | Direction | `<direction slug>` |
+| 3 | <title> | Defer | Revisit after the next run |
+| 4 | <title> | Dismissed | <reason>; guidance `<slug>` taught to future walks |
 
 If `<N> > 0` findings were queued for fix:
 - Prompt the user:
@@ -245,7 +246,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):**
@@ -273,12 +274,13 @@ Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `c
 
 Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
 
-> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open --print>)
+> ☁️ **Cloud:** <full https URL from iamu open --print>
 
 In linked-no-credentials mode, end with `Decisions are local only — iamu auth login, then iamu sync, to share them.` Skip this section entirely in local-only mode. The terminal surface is complete.
 
 ## Guidelines
 
+- **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.

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

@@ -253,12 +253,12 @@ For drafts (no persona): omit `--persona`, omit `--body`.
 
 ### 7. Summarize
 
-Present the created entities with clickable file links and exact run commands:
+Present the created entities by slug, with the scenario file as an absolute path, and exact run commands:
 
 ```
-Created Scenario: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md)
-• Situation: [<outline-slug>](iamu/outlines/<outline-slug>.md)
-• Persona: [<persona-slug>](iamu/personas/<persona-slug>.md)  (or "draft — no persona bound yet")
+Created Scenario: `<scenario-slug>` (<project root>/iamu/scenarios/<scenario-slug>.md)
+• Situation: `<outline-slug>`
+• Persona: `<persona-slug>`  (or "draft — no persona bound yet")
 • Capability: <primary_capability>
 
 Next step:
@@ -271,6 +271,7 @@ Run `iamu validate --all` to verify all entities before reporting done.
 
 ## Guidelines
 
+- **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.
 - **Brainstorm, don't fill forms.** Propose varied seeds. Challenge assumptions. The best scenarios are ones the user hadn't considered.
 - **Problem-space only.** Scenarios describe human situations — never UI, screens, buttons, or features. The walkthrough discovers whether the product supports the situation.
 - **Ground in the domain, not the codebase.** Start from what the persona's week demands. A situation the product cannot support yet is a good scenario: the walk shows the gap with evidence.

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

@@ -69,10 +69,10 @@ Present candidates as scannable numbered cards. Do NOT use multi-column markdown
 
 #### A. When proposing Scenarios:
 
-Lead with existing coverage using clickable links, then render the candidates:
+Lead with existing coverage by slug, then render the candidates:
 
 ```
-Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Uncovered areas: <gaps>.
+Existing coverage: <N> scenarios (`<slug1>`, ...). Uncovered areas: <gaps>.
 
 1. <Short situation name> (<Actor from context>)
    • Capability: <Capability slug, e.g. billing-invoicing>
@@ -116,10 +116,10 @@ You MUST output the proposed candidates to the chat stream FIRST. In the SAME tu
 
 #### B. When proposing Personas:
 
-Lead with existing persona coverage using clickable links and uncovered roles from `context.yml`:
+Lead with existing persona coverage by slug and uncovered roles from `context.yml`:
 
 ```
-Existing personas: [<slug1>](iamu/personas/<slug1>.md), ... Uncovered roles from context.yml: <roles>.
+Existing personas: `<slug1>`, ... Uncovered roles from context.yml: <roles>.
 
 1. <Name> (<Actor role>)
    • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
@@ -179,6 +179,7 @@ Ground rules for generation:
 
 ## Guidelines
 
+- **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.
 - **This skill produces seeds, not finished files.** `iamu-new` handles the full scaffolding. This skill handles the harder upstream question: what and who is worth testing?
 - **Context is load-bearing.** Without project context, you produce the same feature-validation scenarios and generic marketing bios that freeform chat produces. The `context.yml` grounding makes the difference.
 - **Don't pad to 5.** If only 2–3 strong candidates exist, propose 2–3. Padding with weak candidates undermines trust.

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

@@ -349,7 +349,7 @@ Findings never name a human test: the walker does not see them. The judge links
 **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"
+iamu summary <run-id> --worked "What worked 1" --worked "What worked 2" --question "Question for the team" --setup-note "Doubt about the test setup"
 ```
 
 **Post-walk pipeline (MANDATORY — do NOT skip any step):**
@@ -443,10 +443,12 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 5. Present assessment — stay in the conversation
 
-You MUST output the complete Executive Scorecard to the chat stream FIRST. Build it from `iamu report <scenario-slug> --json`: the first row is this run, and its `summary` holds everything below already assembled (verdict, per-test labels, the since-last-run outcome of each earlier finding, findings with titles, where and recommendations, directions, observations). Do not re-read `canonical.json` or `verdicts.json` yourself. Output rich Markdown, not inside a code fence, so tables render and links are clickable:
+You MUST output the complete Executive Scorecard to the chat stream FIRST. Build it from `iamu report <scenario-slug> --json`: the first row is this run, and its `summary` holds everything below already assembled (verdict, per-test labels, the since-last-run outcome of each earlier finding, findings with titles, where and recommendations, directions, observations). Do not re-read `canonical.json` or `verdicts.json` yourself. Output rich Markdown, not inside a code fence, so tables render. Write addresses and file paths out in full so a terminal can open them:
 
 ### <summary.persona> · <summary.situation>
-<summary.steps> steps · [Open in Iamu Cloud](<summary.cloud>) *(local-only: `[report.md](iamu/.runs/<run-id>/report.md)`)*
+<summary.steps> steps · Cloud: <cloud_url, the full https address> *(not on the cloud: the row's `report_path`, the absolute path to report.md)*
+
+If `summary.checks` is set, say first what this run was checking, in one line: `Re-checked <fixes> fixes waiting for a re-check: <fixed> confirmed fixed, <cameBack> came back, the rest not confirmed`, plus the directions that landed. Name the ones that came back.
 
 > **<summary.verdict.question>** **<summary.verdict.label>**
 > <summary.verdict.answer>
@@ -457,9 +459,11 @@ If `summary.since` is set, show what happened to every earlier finding this run
 
 **Since the last run** (<date of summary.since.baselineAt>)
 
-| Earlier finding | Now |
-|---|---|
-| <title> | ✓ Resolved / ✗ Persists / ○ Not seen / ? Unclear |
+| Earlier finding | Now | Notes |
+|---|---|---|
+| <title> | **Resolved** / **Persists** / Not seen / Unclear | <item.note, or — > |
+
+For a persisting finding, put its qualifiers in brackets: the `shift` ("less severe, major → minor") and "the fix did not hold" when `fixedBefore` is true (it was marked fixed before this run).
 
 `+ <summary.since.added> new problems this run.` "Not seen" means the walk did not pass that way: never call it fixed.
 
@@ -483,6 +487,10 @@ 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 the advise step proposed design rule edits (`design_proposals` in its result), add one line: `Design rules: <N> proposed edits (back / challenge / new) — iamu-design to decide`. 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.
+
 Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the scorecard scannable: the tables are the summary.
 
 **Zero-Friction Triage Transition (Eliminate Meta-Prompt Gate):**
@@ -514,7 +522,7 @@ When the user asks to review findings one by one:
    ```markdown
    ### Finding #<N>/<total> [<SEVERITY>] — <title>
    > **Where:** `<Screen title or URL>` (Step <N>) · **Persona:** <Persona Name> (<Role>)
-   > **Evidence:** [step-<N>.png](iamu/.runs/<run>/screenshots/step-<N>.png) · [View in Cloud Walkthrough](<url from iamu open <run-id> --print>)
+   > **Evidence:** <run_dir>/screenshots/step-<N>.png · Cloud: <full https URL from iamu open <run-id> --print>
 
    **❌ Problem:**
    <What went wrong on screen and why it hinders the persona (synthesizing ui_fact and consequence in 1–2 clear, direct sentences)>
@@ -573,7 +581,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>.
@@ -596,7 +604,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. 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`.
@@ -641,6 +649,7 @@ Run `iamu validate --all` to verify all entities before reporting done. If older
 
 ## Guidelines
 
+- **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.
 - **Drafts bind in-line, not as a detour.** If the user picks a draft, the persona-bind step should feel like part of running — not a separate invocation.
 - **All generation is local.** All generation — persona suggestions, brief — uses the local LLM directly. No server-side LLM calls.
 - **Scenario vocabulary.** Say "scenario" — never "outline" — when addressing the user.

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 rules (skippable)** — record the design docs the project already has, or draft rules from intent (`iamu/design.md`).
 - **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.
@@ -228,6 +229,17 @@ iamu set context \
 
 ---
 
+### 4b. Optional: design rules (quick, skippable)
+
+Design is led by intent: the product's design rules are part of its context, like the domain. Run `iamu design detect --json`.
+
+- **Found design docs** (`DESIGN.md`, a design language, interaction principles): list them in one line each and ask whether to record them as the project's design rules. On yes, `iamu design sources <paths…>`. Iamu points at them; they stay the team's documents.
+- **Only tokens or components, or nothing:** say in one line that the project has no written design rules, and offer to draft them from intent now (five short questions, each with a suggested answer) or later. Now: follow **A2** of the `iamu-design` skill, then continue with Step 3/3 below. Later: mention `iamu-design` in the completion handoff.
+
+Never block setup on this. Skipping it is fine; walks still run, and the rules can come any time.
+
+---
+
 ### 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 +337,7 @@ Render the output:
   iamu/
   ├── testability.md       [safety fence active: <target_url>]
   ├── context.yml          [domain: <domain>]
+  ├── design.md            [<N> design rules · <sources>]   (only when recorded)
   ├── personas/
   │   └── <persona-slug>.md
   ├── outlines/
@@ -340,6 +353,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   Write or review the product's design rules (when none were recorded)
 • iamu doctor   Diagnose test environment and target health
 <If cloud_linked: true>
 • iamu sync     Sync completed runs and findings to Iamu Cloud