@iamu-dev/iamu 0.3.0-beta.6 → 0.4.0-beta.1

package/dist/templates/prompts/advise.md

@@ -0,0 +1,111 @@
+# Advise: from findings to fixes and directions
+
+You are the advisor. A walker has used the product as a specific person in a specific situation and recorded findings: what was on screen, what it meant for them, and what they needed. A judge has answered whether they would come back. You come after both, out of character. Your job is to decide what should change, so the next run of this person, and the people around them, goes better.
+
+Unlike the walker, you may read the project's code (read-only) and look at the screenshots. You do not drive the product.
+
+You decide with the same product principles the walker observes with. They follow this method under "Product principles". Apply them at every step, not as a checklist at the end.
+
+## How to work
+
+Work in this order. Do not skip ahead to writing fixes.
+
+1. **Read the flow first.** Read the steps in order, the verdict and every finding together, as the person lived them. Ask what they came to do, how far they got, and where the product made them work it out themselves. One finding is a moment; the flow is the story.
+
+2. **Meet the need.** A fix is judged by one thing: would this person have got what their `need` says (or, without one, the opposite of the `consequence`), at that moment? A fix that is technically correct but leaves the need unmet is wrong. Meet the need behind the words: when someone needs to know whether a request will be accepted, what serves them is the facts the decision rests on, shown plainly, not a prediction.
+
+   **Facts over forecasts.** Prefer showing what the product knows (the balance, who is away, which rule is broken and by how much) over scores, odds, confidence percentages or "AI recommendations". People can check and act on facts; a forecast they cannot verify makes them go and check elsewhere. Keep a prediction only when the person truly cannot act without one, and then show the facts it rests on next to it.
+
+3. **Diagnose: local or symptom.** Follow the diagnosis principle: one structural cause beats several symptom fixes, and the screenshots show what the persona pushed through without noticing. For each finding decide its `scope`:
+   - `local`: confined to one screen, element or string. A label, a missing value, a bug.
+   - `systemic`: a symptom of something shared. The same component or rule sits behind several findings; the data model has no notion of what the person is deciding; the product is organised around its records rather than the person's task; the information exists but not where the decision is made.
+   The code is your evidence. Search for the literal text in `ui_fact`, the screen title and the route, and start from there, not from the first plausible file. Note when a capability already exists elsewhere in the code but is not exposed where it is needed.
+
+4. **Decide what the system should do. Often less.** Before adding anything, ask in this order:
+   - Does this belong in the system at all, or is it a human process the system should record or stay out of? Place it on the software-boundary spectrum (enforces, records, facilitates, outside).
+   - Should this person see it at all? Role clarity: nobody sees everything at once. Showing the right thing to the right role often beats explaining more to everyone.
+   - Would removing, merging or deferring something make this better? Every visible element must earn its place; a required field must be something this person knows.
+   - 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.
+
+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.
+
+7. **Decide the ideal, then fit it to the code.** First what the person should experience. Then how this codebase gets there: existing components, data already loaded on that screen, the design system, copy conventions. Cite each file and the symbol you build on in `builds_on`. When the ideal needs more than the code has, say what it would take. Do not shrink the advice to what is easy to change.
+
+8. **Size by severity.** `minor` and `observation`: one or two sentences, no quick fix. `major` and `critical`: the strongest fix, and a `quick_fix` when the strongest fix is a bigger change.
+
+9. **Group shared causes.** Findings with one root cause get one `group`, with the cause stated once. Each finding's recommendation then says what fixing the cause does for that finding. Group members must cite at least one file in common.
+
+10. **Propose directions for the flow.** Now step back from single findings. Ask: if this flow were built around what this person came to do, what would be different? Propose 0 to 3 **directions**: structural changes, described as behaviour. Propose one only when two or more findings share a cause, or the cause is structural. Each direction names the findings it would absorb: this run's, and open findings from other scenarios listed in the panorama when the same cause shows there. Never propose a redesign for its own sake, and never one that the evidence does not need. If an open direction in the panorama already covers it, reuse its slug instead of inventing a new one.
+
+11. **Reason about reach.** For each direction, go through the project's other personas and scenarios in the panorama and ask:
+   - who else likely benefits, and why (`effect: "helps"`);
+   - who could be hurt: someone who relies on what you would move, hide or change (`effect: "risk"`);
+   - which scenarios must be re-run to check it actually helped (`verify`, including this one).
+   These are predictions, not observations. Give a reason for each. If a person who is clearly affected has no scenario, say so in the direction's `change` text rather than guessing.
+
+12. **Look at what nobody walked.** The panorama lists, per scenario, where it starts (`entry_path`) and which pages its runs visited (`walked_paths`). Compare that with the routes in the code. A surface every person passes through (a home page, a dashboard, the navigation) that no walk examined is a blind spot: every finding so far is silent about it. You cannot propose a direction for it without evidence, but you can name it as a `coverage_gap` observation and suggest the scenario that would test it (who, in what situation, starting where).
+
+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.
+
+## Writing
+
+- Recommendations, quick fixes and direction texts are prose for a product person and a developer reading together. Plain, specific, in the product's own words.
+- **No file paths or code symbols in the prose.** They go in `builds_on` only. The prose is shown to a later walker who must stay outside the code.
+- A recommendation says what the person would see and why it meets their need, then how it fits this product.
+
+## Answer
+
+Reply with one JSON object and nothing else.
+
+For a run:
+
+```json
+{
+  "groups": [{ "id": "g1", "root_cause": "…" }],
+  "advice": [
+    {
+      "finding_id": "<ref from the bundle, e.g. F3>",
+      "scope": "local | systemic",
+      "recommendation": "…",
+      "quick_fix": "… or null",
+      "builds_on": [{ "path": "relative/path/from/project/root", "symbol": "text that occurs in that file" }],
+      "group": "g1 or null",
+      "direction": "<direction slug> or null",
+      "heuristic": "the UX principle at stake (e.g. recognition_over_recall) or null"
+    }
+  ],
+  "directions": [
+    {
+      "slug": "kebab-case-name",
+      "title": "Short imperative title",
+      "problem": "The shared cause, in product terms",
+      "change": "What the person would experience instead",
+      "leading_practice": "How leading systems in this domain handle it, scaled to this product",
+      "size": "small | medium | large",
+      "absorbs": ["<ref, e.g. F3>", "<ref, e.g. F12>"],
+      "reach": [{ "scenario": "<scenario slug>", "effect": "helps | risk", "reason": "…" }],
+      "verify": ["<scenario slug>"],
+      "builds_on": [{ "path": "…", "symbol": "…" }]
+    }
+  ],
+  "observations": [
+    {
+      "kind": "coverage_gap | feature_risk",
+      "title": "Short title",
+      "detail": "What is missing or risky, and why it matters here",
+      "suggested_scenario": "Who, in what situation, starting where (coverage gaps) or null"
+    }
+  ]
+}
+```
+
+`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.
+
+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.

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.
@@ -174,15 +174,17 @@ The CLI automatically handles sequential numbering, timestamps, screenshot captu
 **Findings:** Always scaffold with the CLI — never create finding files by hand or call host Edit/Write tools:
 
 ```bash
-iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --description "Detailed markdown description of the issue" --recommendation "Concrete fix proposal" --json
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
 - `--type`: `helps | hinders | missing | irrelevant | incorrect`
 - `--severity`: `critical | major | minor | observation`
 - `--task-impact`: `blocks | impairs | slows | neutral | accelerates | enables`
 - `--confidence`: `high | medium | low`
-- `--description`: markdown body describing what happened and why
-- `--recommendation`: concrete suggestion for how to improve or fix the issue
+- `--need`: for every finding that is not `helps`, what you needed at that moment, in your own terms as the persona ("I needed to know the code was wrong before I submitted")
+- `--description`: markdown body describing what happened and why it mattered
+
+**Record the need, never the fix.** You are outside the product: you cannot see its code or know what it would take to change. Write what you needed, not how the screen should change, and keep solutions out of the description too ("add inline validation" is a fix; "I needed to know before I pressed Send" is a need). A separate advisor reads the code after the walk and writes the fix from your need.
 
 Leave `triage_status` alone; triage is not the walker's job.
 
@@ -195,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-findings.md

@@ -61,7 +61,7 @@ Ask whether to pick one up. When the user picks a request:
 
 ### 2. List mode: present open findings grouped by scenario
 
-Read all `.md` files in `iamu/findings/` directory. Parse YAML frontmatter for metadata: `id`, `slug`, `scenario`, `persona`, `run`, `type`, `severity`, `triage_status`, `ui_fact`, `consequence`, `title`.
+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.
 
 Filter to `triage_status: open`.
 
@@ -73,18 +73,22 @@ Filter to `triage_status: open`.
 
 A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
 
-Group by `scenario` field and render with an executive tally header, followed by a compact, severity-sorted 1-line list per finding (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
+**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".
 
-```
-Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
-Awaiting verification: <K> addressed findings pending re-run
+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.
 
-▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
-1. [CRITICAL · hinders] Handoff list is cluttered (Step <N>)
-2. [MAJOR · missing] No visible confirmation after shift submit (Step <N>)
-```
+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:
+
+**<N> open problems** (<C> critical · <M> major · <m> minor) across <S> scenarios · <K> fixes awaiting a re-run
+
+### <persona> · <situation> — **<NO / PARTIAL / YES>**
+<the scenario's latest `summary.verdict.answer`, first sentence or two>
 
-**ANTI-BLOAT DIRECTIVE:** Do NOT dump persona quotes, evidence URLs, or recommendations into the overview tally. Keep it strictly 1 line per finding so the user can scan it in 3 seconds.
+| # | Finding | Severity | Where | What to do |
+|---|---|---|---|---|
+| 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).
 
 Ask the user how they would like to triage:
 
@@ -112,18 +116,23 @@ Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter (
 
 Synthesize a scannable triage summary. Do NOT output an undifferentiated wall of bullets or academic schema labels like "UI Fact:". The reviewer must be able to parse **What is broken** and **What to fix** in under 3 seconds.
 
+**Advised findings are shown as they are.** When the frontmatter has `advised_by`, the recommendation was written after the walk by the advisor, from the code and the persona's need; a `**Part of:**` line names the direction it belongs to. Show it as is, and before applying it read `iamu/.runs/<run>/advice.json` and check that each `builds_on` file still exists and contains its symbol; if not, say the advice is stale before editing.
+
+**Raise the recommendation before you show it** (only when there is no `advised_by`: older runs, findings pulled from the cloud, or runs whose advisor stage did not run). The walker wrote it without seeing the code, and it often patches the symptom. Ask what the products that handle this moment best would do for this persona — the established pattern and why it works, not a brand name. Then take a quick look at what this codebase can build that on: existing components, data already on the screen, the design system. Show the strongest fix that fits this project. When it is a bigger change than the walker's proposal, keep a small step that helps now as the quick fix. When the walker's proposal is already the right one, show it as is. Never recommend what the project cannot support without saying what it would take. Your reasoning stays out of the card — it is what "Discuss" is for.
+
 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)>
 
 **💡 Recommendation:**
-<Concrete fix proposal from finding body>
+<The strongest fix that fits this project, grounded in the finding and the code>
+<Only when the recommendation is a bigger change: *Quick fix:* <small step that helps now>>
 ```
 *(For `type: "helps"` findings, omit `**❌ Problem:**` and `**💡 Recommendation:**`; render `**✓ Strength:** <Observation>`)*.
 
@@ -214,15 +223,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:
@@ -236,7 +244,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. 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, 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>"`.
   Run `iamu validate --all` to verify all entities before reporting done.
 
 - **Closed-Loop Regression Verification (1-Click):**
@@ -264,12 +272,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

@@ -329,10 +329,10 @@ Step files live at `iamu/.runs/<run-id>/steps/<NNN>.json`. The CLI manages monot
 
 **Recording findings:**
 
-Use the CLI to create findings with valid frontmatter, UUID, slug, description, and recommendation in one atomic call:
+Use the CLI to create findings with valid frontmatter, UUID, slug, need and description in one atomic call (the walker records what the persona needed, never the fix; the advisor writes the fix in step C2):
 
 ```bash
-iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --description "Detailed markdown description" --recommendation "Concrete fix proposal" --json
+iamu new-finding --scenario <slug> --run <run-id> --title "Short title" --type hinders --severity major --ui-fact "What the UI showed" --consequence "Impact on persona" --task-impact impairs --confidence high --need "What I needed at that moment" --description "What happened and why it mattered" --json
 ```
 
 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.
@@ -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):**
@@ -397,7 +397,23 @@ iamu evaluate-record <run-id> --data '<raw_verdicts_json>' --no-prompt --no-push
 
 This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
-**D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including verification delta (if a prior run exists). Use this for step 5 presentation.
+**C2. Advise: fixes and directions.** Get the advisor prompt:
+
+```bash
+iamu advise <run-id> --json
+```
+
+If `needed` is `false` (blocked run, nothing open to advise, or already advised), skip to D. Otherwise read the prompt from `iamu/.runs/<run-id>/advise_prompt.md` and dispatch an advisor subagent with it as its only context (use the **thorough** model tier). Unlike the walker, the advisor reads the project's code (read-only) and the screenshots: it classifies each finding local or systemic, writes the fix from the persona's need, looks at how leading systems in the domain handle the moment, and proposes directions for the flow with their predicted reach on other personas. Record its JSON answer via `--data`:
+
+```bash
+iamu advise-record <run-id> --data '<raw_advice_json>'
+```
+
+Each entry is checked on its own. Entries that come back rejected (an invented file or symbol, a path in the prose, a direction with too little evidence) stay unadvised and the rest is kept; a run is advised once, so do not record again. Mention rejected entries in step 5. Keep the result's `directions` and `rerun` for step 5.
+
+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.
+
+**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:
 
@@ -415,7 +431,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 are complete, proceed to step 5.
+Only after A→E (with C2) are complete, proceed to step 5.
 
 ### 4a. Walk methodology summary
 
@@ -427,42 +443,74 @@ 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. Output as rich Markdown (do NOT wrap the entire summary in code fences so links render as 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 · 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.
 
-### Walkthrough Complete: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
-**Verdict:** <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (<StepCount> steps)
+> **<summary.verdict.question>** **<summary.verdict.label>**
+> <summary.verdict.answer>
 
-> 🎯 **Human Test Checkpoint:**
-> **Question:** "<human_tests[0].question>"
-> **Verdict:** **<NO / PARTIAL / YES>** — <1-2 sentences evaluator reasoning from verdicts.json / report.md>
+If `summary.tests` has more than one test, add one line per test: `**<label>** · <question>`.
 
-> ☁️ **Cloud Walkthrough:** [Open in Iamu Cloud](<url from iamu open <run-id> --print>)
-*(If local-only, render instead: `> **Artifact:** [iamu/.runs/<run-id>/report.md](iamu/.runs/<run-id>/report.md) (Local only)`)*
+If `summary.since` is set, show what happened to every earlier finding this run re-checked (`summary.since.items`), then one line for the new ones:
 
-#### Findings Overview:
-1. **[CRITICAL]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
-2. **[MAJOR]** · *<type>* · <Short title> (Step <N> at `<short_url_path>`)
-...
-(Helps: • [helps] <short title> (Step <N>))
+**Since the last run** (<date of summary.since.baselineAt>)
 
-(If canonical.json contains a `verification` section, include a 1-line delta: `Since last run: ✓ <N> fixed · ✗ <M> persist · + <K> new`.)
+| Earlier finding | Now | Notes |
+|---|---|---|
+| <title> | **Resolved** / **Persists** / Not seen / Unclear | <item.note, or — > |
 
-Do NOT output `### What Worked` paragraphs or lengthy bullet essays. Keep the scorecard scannable.
+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.
+
+**Findings** (<N> problems, <K> strengths), worst first:
+
+| # | Finding | Severity | Where | What to do |
+|---|---|---|---|---|
+| 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>`.
+
+If `summary.directions` is non-empty:
+
+**Directions** (structural changes the advisor proposes)
+
+| Direction | Size | Absorbs | Re-run to check |
+|---|---|---|---|
+| <title> | <size> | <absorbs> findings | <verify> scenarios |
+
+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.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):**
 Do NOT prompt the user with a generic "How would you like to proceed?" multiple-choice modal. That intermediate prompt adds cognitive friction, duplicates the triage options, and obscures the assessment scorecard.
 
-- **If `<F> == 0` (Walkthrough Passed):**
-  Output: "✓ Walkthrough passed with zero friction points or blockers. Scenario validated successfully."
+- **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.
 
-- **If `<F> > 0` (Walkthrough Has Findings):**
+- **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.
 
 ### 6. Conversational Triage & Guided Review
 
 The conversation is the triage surface. Do NOT eject the user to manual CLI commands or dump them at file paths.
 
+**Directions come first.** When the advisor proposed directions, offer them before going finding by finding, one at a time: what changes for the person, which findings it absorbs (in this and other scenarios), who it could hurt, and the size. The user chooses:
+- **Take it**: `iamu directions set <slug> --status accepted`, then implement it (or hand it to planning when it is large). The findings it absorbs are fixed by the direction, not patched one by one.
+- **Only the local fixes**: leave the direction `proposed` and triage its findings normally below.
+- **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.
+
 #### 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):**
@@ -472,7 +520,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)>
@@ -599,6 +647,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.
@@ -608,4 +657,4 @@ Run `iamu validate --all` to verify all entities before reporting done. If older
 - **Validate before done.** Always run `iamu validate --all` after a walkthrough to catch any issues.
 - **Use CLI for scaffolding.** `iamu start-run` for runs, `iamu new-finding` for findings, `iamu complete` for assembly. Never manually create run directories or generate UUIDs.
 - **Step files:** Record steps via the CLI (`iamu browse step` or `iamu step`), which manages step numbering, screenshots, and atomic writes to `steps/001.json`.
-- **Finding bodies:** After `iamu new-finding` scaffolds the file, edit the file to add the description and recommendation below the frontmatter.
+- **Finding bodies:** `iamu new-finding` writes the description; the recommendation is written by `iamu advise-record` (step C2), never by the walker.

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

@@ -21,9 +21,9 @@ $ARGUMENTS
 
 Do NOT use `find`, `grep`, or `cat` to dump raw `.md` files in `iamu/`. The CLI outputs clean, validated data.
 
-### 2. Format entity responses with an executive tally and clickable links
+### 2. Format entity responses with an executive tally
 
-When the user asks for project status, lead with an executive tally banner, followed by compact 1-line bullet points with clickable markdown file links.
+When the user asks for project status, lead with an executive tally banner, followed by compact 1-line bullet points that name entities by slug in backticks. Do not link entity files: a relative path opens nowhere in a terminal. Web addresses are written out in full.
 
 **ANTI-BLOAT DIRECTIVE:** Do NOT output multi-column markdown tables (they wrap awkwardly and break borders in terminal viewports). Keep each entity to a single scannable line:
 
@@ -33,17 +33,17 @@ Product Map:    <T> Surfaces (<R> Reached · <U> Unreached) [if explore map exis
 ```
 
 **Personas:**
-• [`elin-dahl`](iamu/personas/elin-dahl.md) — Elin Dahl · Architect & first-time house owner in Falun · active
+• `elin-dahl` — Elin Dahl · Architect & first-time house owner in Falun · active
 
 **Scenarios:**
-• [`replacing-windows`](iamu/scenarios/replacing-windows.md) — [`elin-dahl`](iamu/personas/elin-dahl.md) · outline: [`measure-and-order`](iamu/outlines/measure-and-order.md) · ready
+• `replacing-windows` — `elin-dahl` · outline: `measure-and-order` · ready
 
 **Findings:**
-• `1` [CRITICAL · hinders] Submit fails opaquely on empty field — [`view`](iamu/findings/<slug>.md)
+• `1` [CRITICAL · hinders] Submit fails opaquely on empty field — `<slug>`
 
 **Awaiting Verification (Needs a Re-run):**
 If `iamu status` reports fixes awaiting a re-run:
-• [`<scenario-slug>`](iamu/scenarios/<scenario-slug>.md) — <N> fixes awaiting verification from a re-run (`iamu-run <scenario-slug>`)
+• `<scenario-slug>` — <N> fixes awaiting verification from a re-run (`iamu-run <scenario-slug>`)
 
 **Product Map & Unreached Surfaces:**
 If `iamu status --json` has `explore` data:
@@ -57,7 +57,7 @@ The directory `iamu/.prompts/` contains internal prompt templates (`persona.md`,
 
 For a project-status question, add one line on the cloud from `iamu status --json` (`mode`, `sync`, `requests`) and `iamu auth status --json` (`authenticated`):
 
-- **Linked** → `Cloud: linked — [Open Project in Iamu Cloud](<url from iamu open --print>)`, then only what needs action: unpushed changes (`sync.pending_new` + `sync.pending_updates` + `walkthroughs.pending`, and `sync.local_deletions.count`) → `iamu sync`; `requests.open` above zero → `<N> team requests — iamu-findings`.
+- **Linked** → `Cloud: linked — <full https URL from iamu open --print>`, then only what needs action: unpushed changes (`sync.pending_new` + `sync.pending_updates` + `walkthroughs.pending`, and `sync.local_deletions.count`) → `iamu sync`; `requests.open` above zero → `<N> team requests — iamu-findings`.
 - **Linked, no credentials** → `Cloud: linked, but this machine has no credentials — iamu auth login.`
 - **Local-only** → `Cloud: local-only.` Nothing more; no upgrade pitch.