@iamu-dev/iamu 0.0.0-stage → 0.2.0-beta.10

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

@@ -0,0 +1,266 @@
+---
+name: iamu-findings
+description: Triage findings from past walkthroughs — list open findings, review one in depth, act on them (keep / fix / dismiss / rescope). Terminal-complete; dashboard optional.
+generatedBy: __IAMU_VERSION__
+---
+
+Review and triage findings from past walkthroughs. No-arg opens the full list grouped by scenario. With a finding slug or UUID, opens direct triage for that one.
+
+Everything happens in the terminal — no dashboard required. Cloud-linked users get a footer link for rich UI review (step replay, screenshot side-by-side), but quick triage works entirely in chat.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/` exists with findings to review. If `iamu/` does not exist, run `iamu init` and then `iamu-setup` first. If no findings exist yet, run a walkthrough first via `iamu-run`.
+
+## Steps
+
+### 1. Resolve the argument
+
+Two paths based on `$ARGUMENTS`:
+
+- **Finding slug or UUID** → skip to step 3 (direct triage).
+- **No arg** → continue to step 2 (list mode).
+
+**Cloud state** (either path). Run `iamu auth status --json` once:
+
+- **Linked** (`cloud_linked` and `authenticated` both true) → `iamu pull --json` before reading any finding, so teammates' triage decisions are current. Triaging a finding a teammate already closed wastes the session and ends in a sync conflict. Pull never overwrites a local edit (`diverged` lists those — mention them, never `--force`). If pull fails, say so in one line and triage locally.
+- **Linked, no credentials** → say once that decisions stay local until `iamu auth login`, and continue.
+- **Local-only** → nothing to do.
+
+### 1b. Requests from the team (cloud-linked only)
+
+When `iamu/config.json` has `cloud_linked: true` and the `iamu_requests` tool is available, call it once before listing. If it returns `ok: false` (not linked, not authenticated, or `cloud_too_old`), skip this section silently.
+
+If `count > 0`, show the requests first, before the findings tables:
+
+```
+Requests from the team (2)
+  1. Fix     Checkout button unlabeled          Olivia Owner · 3h ago
+  2. Verify  Password reset on mobile           Eddie Editor · 20m ago · claimed by you
+```
+
+One line per request: kind, summary, requester, age, and `claimed by you` / `claimed by <name>` when `status` is `claimed`. Include `note` as an indented second line when present.
+
+Ask whether to pick one up. When the user picks a request:
+
+1. Call `iamu_requests_claim` with its `id`. If it fails with `lease_held`, say who holds it and when the lease expires, and return to the list.
+2. Follow `next` from the result:
+   - `fix` → go to step 4's **Fix now** branch for the finding. The claim payload carries `canonical.findingIds`; open the matching `iamu/findings/*.md` (frontmatter `id`) for the walkthrough context. Use `canonical.uiFact` and `canonical.consequence` as the problem statement.
+   - `verify` or `run` → run `iamu-run <scenario.id>`; offer `scenario.targetUrl` as the target when present.
+3. Tell the user the request closes itself on the next `iamu sync` — step 6 runs it.
+
+**Linked, but the tool is missing** (the iamu-sync server is not registered, or the session started before it was): if `iamu status --json` shows `requests.open` above zero, say `<N> team requests are waiting — run iamu auth login (it registers the iamu-sync server), then restart this session to pick them up here.` Local-only projects have no requests; do not mention them.
+
+### 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`.
+
+Filter to `triage_status: open`.
+
+**Fixed is not proven.** `triage_status: addressed` means a fix was applied. `iamu findings --json` adds `fix_state` to each addressed finding, derived from local runs:
+
+- `awaiting_rerun` — no later run of the scenario has re-checked it. Shown as "awaiting re-run".
+- `verified` — a run that started after the fix saw it working (the since-last-run delta's "Resolved", backed by steps).
+- `recurred` — a run after the fix recorded it again: the fix did not hold. Reopen it (`iamu triage <slug> --status open`).
+
+A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
+
+Group by `scenario` field and render with an executive tally header, followed by a severity-sorted list per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last), including persona quotes, evidence, and clickable file links:
+
+```
+Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
+Awaiting verification: <K> addressed findings pending re-run
+
+▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
+1. [CRITICAL · hinders] Handoff list is cluttered ([file](iamu/findings/<slug>.md))
+   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
+   • Evidence: Step <N> at <url>
+   • Recommendation: Add status filter chips
+
+2. [MAJOR · missing] No visible confirmation after shift submit ([file](iamu/findings/<slug>.md))
+   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
+   • Evidence: Step <N> at <url>
+   • Recommendation: Show inline success toast
+```
+
+Ask the user how they would like to triage:
+
+- **"walk through them"** → iterate through all open findings one-by-one in order with full context, code location, and triage choices (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
+- **"all critical"** → iterate through all critical findings in order.
+- **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
+- **Single number or slug** → single finding (skip to step 3).
+- **"fix 1 and 2"** → make code fixes and mark addressed immediately.
+- **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
+
+**Interactive Triage Strategy:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "How would you like to review these <N> open findings?"
+  - Options:
+    1. "[Recommended] Walk through findings one by one"
+    2. "Focus only on Critical findings (<C> items)"
+    3. "Review by scenario group: <Top Scenario>"
+- Otherwise (in CLI or text-only environments):
+
+How would you like to triage these <N> open findings?
+  1. [Recommended] Walk through findings one by one
+  2. Focus only on Critical findings (<C> items)
+  3. Review by scenario group: <Top Scenario>
+
+Press Enter to walk through all [1], select 2-3, or enter a finding number/slug:
+(Treat empty Enter as Option 1)
+
+### 3. Direct triage: review one finding
+
+Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Inspect the codebase to identify the source file and line responsible. Render full detail with clickable links and evidence:
+
+```
+Finding: <title> ([file](iamu/findings/<slug>.md))
+Scenario: [<scenario>](iamu/scenarios/<scenario>.md)
+Severity: <severity> · Type: <type> · Status: <triage_status>
+
+Persona Quote: "<persona_reaction_or_consequence>"
+UI Fact: <ui_fact>
+Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run>/screenshots/<NNN>.png))
+Source: <file:line path in repository, e.g. src/components/HandoffModal.tsx:42>
+
+Description:
+<markdown body above ## Recommendation>
+
+Recommendation:
+<## Recommendation section, or "none">
+
+Report: [report.md](iamu/.runs/<run>/report.md)
+```
+
+If the finding references a run directory, mention the report path for context. If the user wants to see the screenshot, read from `iamu/.runs/<run>/screenshots/`.
+
+### 4. Prompt for triage action
+
+Every finding must land on a decision — never silently skip. Match the user's intent to the closest option.
+
+**Interactive Triage Selection:**
+*Contextual Recommendation Rule:*
+- If finding is clear, localized, and has a straightforward fix → mark Option 1 as `[Recommended]`.
+- If finding requires architectural touch or redesign → mark Option 2 as `[Recommended]`.
+- If finding is a known trade-off or walker error → mark Option 4 as `[Recommended]`.
+
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Triage Finding: '<finding title>'?"
+  - Options:
+    1. "<[Recommended] if localized> Fix now (apply inline code fix & verify)"
+    2. "<[Recommended] if structural> Design change needed (open issue / design doc)"
+    3. "Defer (revisit in later milestone)"
+    4. "Dismiss / Won't fix (record reason & walker guidance rule)"
+- Otherwise (in CLI or text-only environments):
+
+Triage Finding: '<finding title>'
+  1. Fix now (apply inline code fix & verify)
+  2. Design change needed (open issue / design doc)
+  3. Defer (revisit in later milestone)
+  4. Dismiss / Won't fix (record reason & walker guidance rule)
+
+Press Enter to accept recommendation [1], enter 2-4, or type custom triage note:
+(Treat empty Enter as Option 1)
+
+Record the decision with `iamu triage` — it sets `triage_status` and `triage_note` in `iamu/findings/<slug>.md`, and for a dismissal it also teaches the next walk:
+
+```bash
+iamu triage <slug> --status addressed --note "Made handoff notes optional on /sv/handoff; verified on screen."
+```
+
+The resulting frontmatter:
+
+```yaml
+triage_status: addressed
+triage_note: "Made handoff notes optional on /sv/handoff; verified on screen."
+```
+
+- **Fix now** → the change is small, one-or-two files, no architectural decision needed (label, field made optional, filter added, typo). Make the edit, verify it loads (if a dev server is running, open the affected screen and check), then update frontmatter: `triage_status: addressed` with a one-line change summary in `triage_note`. Do not close a finding as addressed before the change lands and is inspected. Tell the user the fix now awaits a re-run: only a later walkthrough of the scenario turns it verified.
+
+- **Design change needed** → the change requires design thinking (restructuring a flow, new capability, API contract touch, multiple files). Do NOT fix inline. Use the project's own change process if it has one — check the agent docs and the repo for it (an `openspec/` directory and its change skills, an ADR or RFC folder, an issue tracker the docs name) and start the change there with the finding's persona + scenario context pre-filled. Only if the project has none, draft a short design doc. Then leave the finding `open` until the change ships. Attach the change reference in `triage_note`: `"Design change: <reference>. Re-triage when the change ships."`.
+
+- **Defer** → the finding is real but not urgent. Set `triage_status: deferred` with an explicit `triage_note` naming the condition to revisit: `"Defer: revisit after <trigger, e.g. Q3 mobile release / next round of persona feedback>."`.
+
+- **Won't fix (accepted trade-off)** → the problem is real but the team accepts it. `iamu triage <slug> --status wont_fix --note "<the trade-off>"`. It stays out of future walks' dismissed list only as a known issue — no guidance rule is written.
+
+- **Not relevant / walker got it wrong** → the finding should never have been reported. Ask which, because they teach different things:
+  - *Not relevant* (by design, out of scope): `iamu triage <slug> --status dismissed --reason not_relevant --note "<why it is not a problem>"`.
+  - *Walker error* (the walker misread the screen): `iamu triage <slug> --status dismissed --reason walker_error --note "<what it misread>"`.
+  - *Duplicate* of another finding: `--reason duplicate --note "Duplicate of <slug>"` (no rule is written).
+
+  Not relevant and walker error write a **tester guidance rule** to `iamu/guidance/<slug>.md` that every later walker reads (and the matcher uses to flag repeats). The rule text defaults to "Don't report: <title>"; pass `--rule "<one sentence the walker can act on>"` when the title is too narrow or too broad. The rule applies to the whole project unless you pass `--scope outline` or `--scope capability` — narrow it when the finding is only irrelevant in this situation. Several findings dismissed for the same reason go in one call and share one rule. **Tell the user: "Dismissed — future walkthroughs are told not to report this"** and name the rule file. One-word notes ("nope") degrade future runs — name the reason specifically.
+
+- **Keep (no decision yet)** → rare. Use only when the reviewer genuinely needs more information. Leave `triage_status: open` and add a `triage_note` noting what you are waiting for: `"Waiting on <thing> before triage."`.
+
+Report back with the action taken:
+
+```
+addressed (fix now): <finding-slug>
+  Change: made handoff notes optional on /sv/handoff
+
+deferred: <finding-slug>
+  Note: revisit after Q3 mobile release
+
+dismissed (duplicate): <finding-slug>
+  Reason: duplicates frontline-worker--incident-report-overwhelm-a7b2c1
+
+dismissed (not_relevant): <finding-slug>
+  Reason: the beta badge is intentional until launch
+  Guidance: iamu/guidance/dont-report-the-beta-badge.md (whole project)
+```
+
+### 5. Continue or close
+
+If the user is in list-mode iteration (picked "all critical" or a scenario group), loop to step 3 for the next finding in the queue. Otherwise close.
+
+Summary at the end (list-mode only):
+
+```
+Triage complete.
+  Fixed: <N>
+  Dismissed: <N>
+  Rescoped (design change / defer): <N>
+  Kept open: <N>
+
+<X> findings remain open. Use iamu-findings to resume later.
+```
+
+Run `iamu validate --all` to verify all entities before reporting done.
+
+### 6. Publish and link (linked mode only)
+
+Triage decisions are team state: until they sync, teammates still see these findings as open and a request for them stays open. If any finding changed this session, run once at the end — not after every decision:
+
+```bash
+iamu sync --json
+```
+
+Report it in one line: `Synced <N> findings to Iamu Cloud.` If the result has `conflicts`, a teammate changed the same finding: name it and give the resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours). If it has `pending_deletes`, list them and tell the user to run `iamu sync --confirm-deletes` after checking. Never run `--keep-mine` or `--confirm-deletes` yourself — only the user decides to overwrite or delete team data.
+
+Then end with the dashboard link from `iamu open --print` (step replay, screenshots side by side, the team's view of the same findings):
+
+```
+Team view: <url>
+```
+
+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
+
+- **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.
+- **Screenshot paths over inline images.** Skill prints `iamu/.runs/<run>/screenshots/step-<N>.png` paths. Agents with image-capable read can open them on request.
+- **Every finding gets a decision — none disappear silently.** Fix now, design change, defer, won't fix, or explicit "waiting on X". No finding exits triage unreviewed. This discipline is load-bearing: silent skips degrade the signal the next walkthrough depends on.
+- **Bias toward small, direct fixes.** If something can be fixed in five minutes without risk, do not create a design process for it — fix it now and triage as addressed with a one-line change summary.
+- **Design change for anything that needs thinking.** Multiple files, API contracts, flow restructuring, new capability — do NOT fix inline. Pre-fill the proposal with the finding's persona + scenario context so the human thread survives the handoff from walkthrough to PR.
+- **Required note on dismiss.** Do not let findings disappear without a reason captured. The note becomes the reason on the tester guidance rule future walkers read. One-word dismissals ("nope", "invalid") are anti-signal — name the reason specifically: duplicate of `<slug>`, not in scope for `<release>`, persona mismatch, known limitation tracked elsewhere, etc.
+- **Match the note to the action.** Fix-now notes describe what changed. Design change notes name the reference. Defer notes name the revisit condition. Won't-fix notes name the reason. Do not reuse "LGTM" or "done" — the next triager reads these out of context months later.
+- **Local-only users get parity.** No dashboard mention, no "upgrade" prompts. Full workflow in chat.
+- **`iamu triage` is the triage path.** It validates the status and reason, keeps the body, and writes the guidance rule. Edit the finding file by hand only for fields it does not set. Rules in `iamu/guidance/` are plain markdown: edit the text, or set `status: retired` to stop a rule without deleting its history.
+- **Deleting is a cloud act too.** Deleting a finding file (or a run directory) that this machine synced deletes it on the cloud at the next `iamu sync`; a run whose findings are still in `iamu/findings/` is kept. Triage (`dismissed`, `wont_fix`) keeps the history — prefer it. When many are deleted at once, sync lists them and waits for `iamu sync --confirm-deletes`, which only the user runs.
+- **New findings during triage.** If triage reveals a new issue, use `iamu new-finding` to scaffold it with valid frontmatter — do not manually create finding files.
+- **Validate before done.** Always run `iamu validate --all` after editing findings to catch any issues. For legacy files that fail on schema drift, `iamu validate --all --fix` (preview with `--dry-run`) repairs the mechanical part; never hand-fill a missing `run`, `scenario`, or `persona` with a guess.
+- **Requests are dispatch records, not tickets.** Never ask the user to update one; the cloud closes it from the synced finding or run.

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

@@ -0,0 +1,263 @@
+---
+name: iamu-new
+description: Draft a scenario or standalone persona from a specific intent — create the situation + persona + brief, or scaffold a standalone persona into the casting panel. Use when the user already knows WHAT or WHO to test. If they're exploring what or who to test or need suggestions, use iamu-propose first.
+generatedBy: __IAMU_VERSION__
+---
+
+You are a brainstorming partner, not a form filler. Your job is to help the user discover scenarios that will stress-test their product in ways they haven't thought of.
+
+**You bring:**
+- Understanding of the domain from `iamu/context.yml` (actors, jurisdiction, regulations if applicable)
+- Knowledge of the codebase from prior exploration (what features exist, what flows are built)
+- Awareness of the gap between "what the product supports" and "what real users actually need to do"
+
+**The user brings:**
+- Knowledge of which area they want to test (or nothing — you propose)
+- Judgment on what feels realistic vs. contrived
+
+Scenarios are written in **problem-space only** — they describe human situations, not UI flows. No screen references, no button names, no feature names. The scenario says "a shift leader needs to hand off open incidents under time pressure" — the walkthrough discovers whether the product supports that.
+
+**Methodology prompts:** Before drafting, read the methodology files. These contain the quality standards for each artifact:
+- `iamu/.prompts/persona.md` — how to write a durable persona
+- `iamu/.prompts/outline.md` — how to write a situation outline
+- `iamu/.prompts/combine.md` — how to combine persona + outline into a scenario with emergent test questions
+
+Follow these methodologies. They define what quality looks like.
+
+$ARGUMENTS
+
+## Prerequisites
+
+Before starting, check that `iamu/context.yml` exists and has `domain` filled in. If it is missing or empty, run the `iamu-setup` skill first — context grounds every scenario draft and walkthrough downstream. If `iamu/` does not exist at all, run `iamu init` first.
+
+## Steps
+
+### 1. Understand what to test or draft
+
+Determine the mode based on `$ARGUMENTS` and user intent:
+
+- **Standalone Persona mode** (e.g. `iamu-new "persona Maria Gomez"`, `iamu-new "Maria Gomez"`, or when the user wants to add an actor/tester to the casting panel):
+  1. Ground in `iamu/context.yml` actors, domain, and jurisdiction.
+  2. Define role, disposition, key biases, friction triggers, and domain vocabulary.
+  3. Propose the persona candidate to the user (name, role, disposition, expectations).
+  4. Once confirmed, scaffold the persona into `iamu/personas/`:
+     ```bash
+     iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
+     ```
+  5. Write the persona's background narrative and test expectations as the markdown body.
+  6. If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field to match an existing product account/role.
+  7. Run `iamu validate --all`.
+  8. Summarize: persona created in `iamu/personas/<slug>.md`. Prompt user: "You can now pair `<slug>` with a scenario draft via `iamu-new`, or propose situations for them via `iamu-propose`." Stop here for standalone persona requests.
+
+- **Fast-Path Scenario mode** (when intent, topic, or a handoff candidate from `iamu-propose` is provided, e.g. `iamu-new "checkout friction"`, `iamu-new "Maria Gomez shift handoff"`):
+  Do NOT drag the user through multiple question modals. Skip Step 2 entirely!
+  Jump directly to Step 3 and present the **Complete Scenario Spec-Sheet** (Situation + Bound Persona + Preconditions + Evaluation Checkpoint + Walker Brief) for **1-click / 1-key acceptance**.
+
+- **Exploratory Scenario mode** (no arguments or broad exploration):
+  Proceed through Step 2 (Propose complete scenario bundles) and Step 3.
+  Inspect `iamu/personas/` (`iamu list personas`) first. If personas already exist in the casting panel (e.g. seeded during `iamu-setup`), deliberately frame scenario proposals around those existing cast members to build longitudinal test history, rather than inventing new personas.
+  If the user gives a direction, ground it in the codebase: what capabilities exist in this area? What flows are built? This helps you propose scenarios that test what's actually there, not what's imagined.
+
+### 2. Propose Complete Scenario Bundles (Exploratory Mode)
+
+Present 2–3 scannable scenario proposals. Each proposal MUST bundle the situation narrative, bound persona (prioritizing existing cast members), human evaluation checkpoint, and entry surface:
+
+```
+1. <Title> (<Primary Capability>)
+   • Persona: <Persona Name> (<Role>) — Reused from cast / New candidate
+   • Tension: <1 concise sentence on the human or organizational tension>
+   • Evaluation Checkpoint: "<Concrete binary yes/partial/no question>"
+   • Entry Surface: `<entry_path>` (Target: `<target_url>`)
+
+2. <Alternative Title> (<Capability>)
+   • Persona: <Alternative Persona Name> (<Role>)
+   • Tension: <1 concise sentence>
+   • Evaluation Checkpoint: "<Concrete binary question>"
+   • Entry Surface: `<entry_path>`
+```
+
+**Interactive Decision:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Scaffold this scenario for walkthrough?"
+  - Options:
+    1. "[Recommended] Scaffold '<Bundle 1 Title>' as <Persona 1 Name>"
+    2. "Switch persona: Walk as <Alternative Persona Name> (<Role>)"
+    3. "Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>"
+    4. "Customize situation, checkpoint, or preconditions"
+- Otherwise (in CLI or text-only environments):
+
+Scaffold this scenario for walkthrough?
+  1. [Recommended] Scaffold '<Bundle 1 Title>' as <Persona 1 Name>
+  2. Switch persona: Walk as <Alternative Persona Name> (<Role>)
+  3. Select alternative: '<Bundle 2 Title>' as <Persona 2 Name>
+  4. Customize situation, checkpoint, or preconditions
+
+Press Enter to scaffold [1], select 2-3, or type adjustments:
+(Treat empty Enter or return as Option 1)
+
+*Execution Flow:*
+- **Selecting Option 1 (or hitting Enter):** Proceed IMMEDIATELY to Step 6 (Persist everything). Zero intermediate question modals.
+- **Selecting Option 2:** Present the persona switcher (Step 4) then persist.
+- **Selecting Option 3:** Swap primary bundle and prompt to persist.
+- **Selecting Option 4 / typing adjustments:** Expand into Step 3 to refine details before persisting.
+
+### 3. Develop the situation (Scenario Spec-Sheet)
+
+In Fast-Path mode or when customizing, present the complete scenario as a structured, scannable Spec-Sheet before creating anything. Every field shown here is written verbatim to disk on confirmation:
+
+Do NOT use markdown blockquote syntax (`>`), which renders as stray `|` pipe characters in terminal frontends. Keep the narrative capped at 2–3 punchy sentences (problem-space only, zero UI terms).
+
+```
+### Scenario Spec-Sheet: <Outline Title>
+
+Situation & Stakes:
+  Narrative:    <2–3 sentences problem-space only, zero UI terms>
+  Tension:      <Colliding needs in X vs Y format or "None">
+  Evaluation Checkpoint: <Concrete binary yes/partial/no question scored at evaluation>
+
+Roles with Stakes:
+  • <Role 1>: <Stake>
+  • <Role 2>: <Stake>
+
+Execution Preconditions (resolved at iamu-run):
+  • Assumed State: <What records/data should exist, e.g. "Department with existing risk register containing open hazards">
+  • Squint Guidance: <How the walker should approximate if exact records are missing, e.g. "If no packaging hazard exists, select any physical safety hazard and proceed with delegation">
+  • Reachable Surface: <Entry route matched against iamu/testability.md, e.g. "/incidents/new">
+
+Persona & Brief:
+  Persona:      <Existing slug from panel OR new candidate: Name (Role)>
+  Friction:     <Diagnostic friction trigger and bounce risk>
+  Walker Brief:
+    "<First-person brief in persona voice (2–3 sentences). Describes what they intend to achieve before touching the product. Written verbatim to scenario markdown body.>"
+
+If the situation requires an un-mocked endpoint or missing data fixture to be walkable, offer to scaffold the missing MSW handler (e.g. in `src/mocks/handlers.ts`) or fixture file directly in the codebase before finalizing.
+```
+
+**Interactive Draft Confirmation:**
+- If your environment provides an interactive user-prompt tool, invoke it:
+  - Question: "Scaffold scenario '<Outline Title>'?"
+  - Options:
+    1. "[Recommended] Scaffold scenario and prepare walkthrough"
+    2. "Switch persona: Walk as <Alternative Persona> (<Role>)"
+    3. "Adjust checkpoint, preconditions, or surface"
+- Otherwise (in CLI or text-only environments):
+
+Scaffold scenario '<Outline Title>'?
+  1. [Recommended] Scaffold scenario and prepare walkthrough
+  2. Switch persona: Walk as <Alternative Persona> (<Role>)
+  3. Adjust checkpoint, preconditions, or surface
+
+Press Enter to scaffold [1], select 2, or type adjustments:
+(Treat empty Enter or return as Option 1)
+
+*Selecting Option 1 or hitting Enter proceeds IMMEDIATELY to Step 6 (Persist everything).*
+
+### 4. Pick or swap personas (on demand)
+
+Triggered only when the user selects "Switch persona", when exploring standalone personas, or when no existing persona fits:
+
+**Check existing personas first:**
+Inspect `iamu/personas/` (`iamu list personas`). If an existing persona in the casting panel is a natural fit for this situation, propose them first to build longitudinal test history:
+`Reusable from panel: <slug> (<role>) — <why they fit this situation>`
+
+If no existing persona fits, or if testing an uncovered perspective is needed, propose 2–3 persona candidates as numbered cards (do NOT use a wide table):
+
+```
+1. <Name> (<Role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Why this tests something different: <Unique perspective or workflow divergence>
+
+2. <Name> (<Role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Why this tests something different: <Unique perspective or workflow divergence>
+```
+
+**Interactive Persona Selection:**
+- If your environment provides an interactive user-prompt tool, invoke it with the candidates:
+  - Question: "Which persona should walk this scenario?"
+  - Options:
+    1. "[Recommended] Bind existing persona: <slug> (<role>)" (if one fits)
+    2. "Create candidate: <Name> (<Role>)"
+    3. "Leave as draft (no persona bound yet)"
+- Otherwise, prompt: "Pick a persona (1–N), 'new' to propose candidates, or 'skip' to save as draft without a persona."
+
+### 5. Classify into capabilities
+
+Situations carry ONE primary capability (product area grouping) and optional secondary capabilities (cross-cutting tags). Read existing capabilities directly from `iamu/capabilities/` or `iamu/context.yml`.
+
+Do NOT execute interactive bash commands (like `iamu list capabilities`) during conversational turns; resolve capabilities silently from workspace files.
+
+- **High confidence match** → assign silently, one line: `Capability: <slug> (auto)`
+- **Low confidence or new** → ask: "Create new capability `<slug>`?"
+
+Don't let capability selection derail the conversation. It's a label, not a design decision.
+
+### 6. Persist everything
+
+Use CLI commands to scaffold entities with valid frontmatter. The CLI generates UUIDs and validates against schemas.
+
+**Order matters** — write referenced entities first:
+
+**1. Capability** (only if new):
+```bash
+iamu new capability --name "Incident Reporting" --description "What staff can do when something goes wrong on shift" --json
+```
+
+**2. Outline** (the situation — problem-space, no UI references):
+```bash
+iamu new outline --name "Busy shift handoff" \
+  --capability incident-reporting \
+  --tension "Incident details are fragmented across multiple logs while shift time expires" \
+  --narrative "A shift leader needs to hand off a set of open incidents to the incoming supervisor." \
+  --human-test "Could the incoming leader act immediately without asking clarifying questions?" \
+  --json
+```
+The `--capability`, `--tension`, `--narrative`, and repeatable `--human-test` flags populate outline frontmatter directly. The outline body stays empty. If specialized fields like `situation_roles` are needed, edit the generated frontmatter.
+
+**3. Persona** (if user picked a new persona to scaffold):
+```bash
+iamu new persona --name "Maria Gomez" --role "Site Safety Coordinator" --disposition "Time-pressured, prefers physical paper over complex forms" --json
+```
+The `--role` and `--disposition` flags populate frontmatter directly. If `iamu/context.yml` has an `access` mechanism, also set the persona's `access` to the account, role, or switcher key that matches this persona in the product — check what users the product actually has rather than inventing one; leave it out if nothing fits and say so. Write the persona's background narrative and test expectations as the markdown body.
+
+**4. Scenario** (the binding):
+```bash
+iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez [--entry /path/on/the/product] [--state-description "<Assumed state description>"] [--state-approximation "<Squint guidance for walker>"] --body "<First-person brief in persona voice (3–5 sentences)>" --json
+```
+When the situation begins on a specific page (the persona follows a link from a video, an email, a search result), add `--entry /path/on/the/product` — the run starts there instead of the home page.
+`--outline` is required. `--persona` is optional (omit for drafts). Pass `--state-description` and `--state-approximation` if preconditions were defined in step 3 to populate the scenario's `state:` frontmatter automatically.
+
+For drafts (no persona): omit `--persona`, omit `--body`.
+
+### 7. Summarize
+
+Present the created entities with clickable file links 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")
+• Capability: <primary_capability>
+
+Next step:
+  iamu-run <scenario-slug>              # Run walkthrough as <persona-name>
+```
+
+Run `iamu validate --all` to verify all entities before reporting done.
+
+**Cloud-linked projects** (`iamu auth status --json` → `cloud_linked` and `authenticated` both true): after validation, run `iamu sync --json` so teammates see the new scenario and personas, and add one line to the summary: `Shared with your team on Iamu Cloud.` A draft (no persona) does not push until a persona is bound — say so instead (`draftsSkipped` in the result). On conflicts or errors, report them in one line and leave resolution to the user. Local-only projects: nothing.
+
+## Guidelines
+
+- **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 codebase.** Use your knowledge of what the product actually does to propose scenarios that stress-test real capabilities. But keep the scenario language product-agnostic.
+- **Present before creating.** Show situation, personas, and capability to the user before writing files.
+- **Scenario vocabulary.** Say "scenario" in output, never "outline" or "capability."
+- **Multiple personas surface different problems.** A manager, a field worker, and an auditor will find completely different issues in the same situation. Propose personas that test the product differently, not personas that are cosmetically varied.
+- **Personas are durable cast members.** Personas live in `iamu/personas/` and can be tested across multiple scenarios over time. When creating new personas, define realistic friction, biases, and domain vocabulary—not generic marketing fluff. Prioritize reusing existing personas before minting new ones.
+- **Draft mode is a real option.** Users who want to think about persona later should get it.
+- **Capability is quiet.** High-confidence matches fire silently.
+- **Slug references are load-bearing.** Write referenced entities before the entities that reference them.
+- **Validate before done.** Always run `iamu validate --all` after writing entities.
+- **Use CLI for scaffolding.** `iamu new <type>` creates valid frontmatter with UUIDs. Pass flags (`--role`, `--disposition`, `--capability`, `--tension`, `--human-test`, `--state-description`) directly instead of manual YAML editing.