@iamu-dev/iamu 0.2.0-beta.1 → 0.2.0-beta.10

package/dist/templates/prompts/walk.md

@@ -70,11 +70,9 @@ Continuity: steps form ONE ongoing monologue. From step 2 onward, don't restate
 
 ## Pacing
 
-**Aim for 10-20 steps.** Stop when the primary task verdict is clear — either the persona accomplished their goal or they hit friction that blocks them. A focused 12-step walkthrough with sharp findings is worth more than a 40-step exhaustive tour.
+**Aim for 10-20 steps.** When evaluating a form or journey, inspect all relevant sections across the workflow (e.g., travel details, per diem, deductions, expenses). Do not abandon the walkthrough after logging a single defect — continue through the remaining sections to uncover all distinct compliance and usability gaps before completing. A complete walkthrough with sharp findings across all sections gives the team high-value signal.
 
-Do not try to complete every interaction. If a form has 15 fields, the observation is "this persona would give up at field 4" — note the finding and move on.
-
-Do try key interactions that reveal something: click the main CTA, open a dropdown, check what filters exist. These are cheap observations with high signal.
+Do try key interactions that reveal something: click the main CTA, open a dropdown, check what options or deductions exist. These are cheap observations with high signal.
 
 Follow the persona's motivation. Spend time on what matters to them. When you have enough evidence to answer "would this person come back?" — you're done.
 
@@ -100,6 +98,20 @@ Your browser tooling has limitations that can look like product bugs. Before rec
 
 Do NOT silently suppress findings you suspect are tooling issues. Record them with the caveat — the human triaging can verify.
 
+## Expected state vs product bugs (Empty state & unseeded data)
+
+When an environment is unseeded or test records are missing:
+- An empty table or "No records found" screen is NOT automatically a product bug. If your scenario assumes existing data (e.g. reviewing past entries or auditing submitted claims), check whether the environment simply lacks seed data.
+- If your persona role is a creator (e.g. employee or consultant creating an item), click the creation CTA (e.g. "+ Ny reseräkning", "+ New") and proceed with your task.
+- If your persona role is read-only (e.g. an auditor or manager) and cannot create data, do NOT record false "missing data" bugs against the product. Conclude the walk noting that the environment lacks the required preconditions.
+
+## Semantic squinting (Adapting to environmental mismatch)
+
+Your prompt may include an approximation strategy (e.g. "If Malmö is missing, choose Göteborg").
+- **Squint at the closest match:** When the exact target name, category, or record described in your brief isn't available in this environment, pick the closest available alternative that allows testing the workflow.
+- **Stay in the journey:** Approximation is bounded. Never drift to unrelated modules (e.g. settings, profile, admin panels) just because a specific test record was absent.
+- **Log the approximation:** In your step note (`note`), state clearly that you chose the closest alternative according to your instructions.
+
 ## Portal-rendered UI
 
 Radix / Headless UI / Floating UI render dropdowns and listboxes into portals that do not appear in accessibility snapshots. If an expandable combobox looks empty after click, try: press ArrowDown then Enter, or evaluate a script in the page to probe the DOM. Take a fresh screenshot.

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

@@ -67,47 +67,63 @@ 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 as a severity-sorted table per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
+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:
 
 ```
-Open findings (N total)
-
-▼ maria-gomez--busy-shift (4 findings)
-
-| # | Severity | Type    | Finding                                          | Slug                                                       |
-|---|----------|---------|--------------------------------------------------|------------------------------------------------------------|
-| 1 | CRITICAL | hinders | Handoff list is cluttered                        | maria-gomez--busy-shift--handoff-list-cluttered-a1b2c3     |
-| 2 | MAJOR    | missing | No visible confirmation after shift submit       | maria-gomez--busy-shift--no-submit-confirmation-d4e5f6     |
-| 3 | MINOR    | hinders | Timeout warning fires mid-input                  | maria-gomez--busy-shift--timeout-mid-input-g7h8i9          |
-| 4 | OBS      | helps   | Gesture hint at top of screen                    | maria-gomez--busy-shift--gesture-hint-j1k2l3               |
-
-▼ dev-patel--checkout-abandon (3 findings)
-
-| # | Severity | Type      | Finding                                          | Slug                                                       |
-|---|----------|-----------|--------------------------------------------------|------------------------------------------------------------|
-| 5 | CRITICAL | incorrect | Cart total recalculates to wrong amount          | dev-patel--checkout-abandon--cart-total-wrong-...          |
-| 6 | MAJOR    | missing   | No save-for-later affordance                     | dev-patel--checkout-abandon--no-save-for-later-...         |
-| 7 | MINOR    | hinders   | Auto-scroll on form error                        | dev-patel--checkout-abandon--auto-scroll-error-...         |
+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 which finding to triage (by number, slug, or "skip").
+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.
+- **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. Render full detail:
+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>
-Slug: <slug>
-Scenario: <scenario>
-Type: <type>  Severity: <severity>  Triage: <triage_status>
+Finding: <title> ([file](iamu/findings/<slug>.md))
+Scenario: [<scenario>](iamu/scenarios/<scenario>.md)
+Severity: <severity> · Type: <type> · Status: <triage_status>
 
-UI fact: <ui_fact>
-Consequence: <consequence>
+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>
@@ -115,16 +131,38 @@ Description:
 Recommendation:
 <## Recommendation section, or "none">
 
-Linked run: iamu/.runs/<run>/report.md
+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
 
-Ask: "What should happen with this finding?"
-
-Every finding must land on a decision — never silently skip. The six options below cover the real workflow: two that chain into code changes, one that parks with context, two that close with rationale (an accepted trade-off, or never a problem at all), one that leaves it for later review. Match the user's intent to the closest option; do not shoe-horn.
+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:
 

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

@@ -49,86 +49,143 @@ Determine the mode based on `$ARGUMENTS` and user intent:
   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.
 
-- **Scenario mode** (e.g. `iamu-new "checkout friction"`, or no `$ARGUMENTS`):
-  Proceed through steps 2–7 below.
-  Inspect `iamu/personas/` (`iamu list personas`) first. If personas already exist in the casting panel (e.g. seeded during `iamu-setup`), deliberately frame scenario seeds around those existing cast members to build longitudinal test history, rather than inventing new personas.
+- **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 scenario seeds
+### 2. Propose Complete Scenario Bundles (Exploratory Mode)
 
-Propose 2–3 scenario seeds in a compact comparison table fitting the terminal viewport. If personas exist in `iamu/personas/`, explicitly indicate which existing persona pairs with each seed concept. Do not write full paragraphs or full scenarios until a direction is picked.
+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:
 
 ```
-| # | Seed Concept | Persona / Actor | Type | Human Situation & Core Tension | What It Stress-Tests |
-|---|--------------|-----------------|------|--------------------------------|----------------------|
-| 1 | <Short title> | <existing slug or role> | Routine | <1-2 sentences on who is doing what> | <What this tests> |
-| 2 | <Short title> | <existing slug or role> | Edge case | <1-2 sentences on uncommon situation> | <What this tests> |
-| 3 | <Short title> | <existing slug or role> | Tension | <1-2 sentences on conflicting needs> | <What this tests> |
+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>`
 ```
 
-Ask the user: "Which seed should we develop (1–3), or suggest another angle?"
+**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
 
-### 3. Develop the situation
+Press Enter to scaffold [1], select 2-3, or type adjustments:
+(Treat empty Enter or return as Option 1)
 
-Once the user picks a direction, draft the full situation:
+*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.
 
-- **Narrative** (3–5 sentences) — mundane specifics, not abstract test language. Time pressure, competing priorities, real constraints. Write it as a human story.
-- **Tension** (usually null; set only when two legitimate needs genuinely collide — e.g., speed vs. thoroughness, privacy vs. transparency)
-- **Situation roles** (2–4 people with stakes) — each person should see the situation differently. Not conflict for drama — realistic tension like: one person wants to move on, another wants to investigate.
-- **Complexity level**
+### 3. Develop the situation (Scenario Spec-Sheet)
 
-**Before finalizing**, ask the user: "What should this walkthrough focus on?" This is the research question — what they want to learn. Examples: "Can a new admin onboard without training?", "Does the checkout flow work under time pressure?", "Is the reporting workflow accessible to non-technical users?"
+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:
 
-From their answer, derive ONE concrete human test — a specific yes/partial/no checkpoint the evaluation step will score. Suggest it and let the user refine:
+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).
 
-> Focus: "Can a new admin onboard without training?"
-> Human test: "Could the admin complete employee bulk-import without consulting documentation?"
+```
+### Scenario Spec-Sheet: <Outline Title>
 
-The user's focus frames the overall assessment after the walkthrough. The human test is a concrete checkpoint that feeds into it.
+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>
 
-Present the draft to the user as a structured, scannable block **before creating anything**:
+Roles with Stakes:
+  • <Role 1>: <Stake>
+  • <Role 2>: <Stake>
 
-```
-### Situation Draft: <Name>
+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">
 
-> **Narrative:** <3–5 sentences describing the human situation without mentioning UI>
->
-> **Tension:** <legitimate colliding needs or "None">
-> **Focus Question:** <user's research question>
-> **Human Checkpoint:** <derived checkpoint question>
+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.>"
 
-**Roles with Stakes:**
-- **<role>**: <stake>
-- **<role>**: <stake>
+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.
 ```
 
-User approves, refines ("make it more time-pressured"), or rejects.
+**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 propose personas
+### 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 in a compact table:
-
-- Different roles (the manager vs. the field worker vs. the auditor)
-- Different dispositions (the patient learner vs. the harried pragmatist)
-- Different contexts (first time vs. experienced, desktop vs. mobile, fluent vs. second-language)
+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):
 
 ```
-| # | Name | Role | Why this persona tests something different |
-|---|------|------|-------------------------------------------|
-| 1 | ... | ... | ... |
-| 2 | ... | ... | ... |
-| 3 | ... | ... | ... |
+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>
 ```
 
-The user picks one (or more — each becomes a separate scenario). "New" to propose different candidates. "Skip" to save as draft without a persona.
+**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 from `iamu/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>`?"
@@ -148,18 +205,14 @@ iamu new capability --name "Incident Reporting" --description "What staff can do
 
 **2. Outline** (the situation — problem-space, no UI references):
 ```bash
-iamu new outline --name "Busy shift handoff" --json
-```
-After creation, use Edit to add fields to the frontmatter: `primary_capability`, `narrative`, `tension`, `human_tests`, `situation_roles`. The outline body stays empty.
-
-Example frontmatter to add via Edit:
-```yaml
-primary_capability: incident-reporting
-narrative: "A shift leader needs to hand off a set of open incidents..."
-human_tests:
-  - id: ht-1
-    question: "Could the incoming leader act immediately without asking clarifying questions?"
+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
@@ -169,21 +222,25 @@ The `--role` and `--disposition` flags populate frontmatter directly. If `iamu/c
 
 **4. Scenario** (the binding):
 ```bash
-iamu new scenario --name "maria-gomez--busy-shift-handoff" --outline busy-shift-handoff --persona maria-gomez --json
+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). Write the first-person brief as the markdown body — 3–5 sentences in the persona's voice.
+`--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 the brief body.
+For drafts (no persona): omit `--persona`, omit `--body`.
 
 ### 7. Summarize
 
+Present the created entities with clickable file links and exact run commands:
+
 ```
-Scenario: <scenario-slug>
-Situation: <situation name>
-Persona: <persona-name>   (or "draft — no persona yet")
+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>
 
-Run it:  iamu-run <scenario-slug>
+Next step:
+  iamu-run <scenario-slug>              # Run walkthrough as <persona-name>
 ```
 
 Run `iamu validate --all` to verify all entities before reporting done.
@@ -203,4 +260,4 @@ Run `iamu validate --all` to verify all entities before reporting done.
 - **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. Use Edit to add additional fields and body content after scaffolding.
+- **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.

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

@@ -33,15 +33,19 @@ If context is thin (few actors, sparse notes), say so upfront — "your context
 
 ## Steps
 
-### 1. Load domain context
+### 1. Load domain context & testability boundaries
 
 Read `iamu/context.yml`. Extract and hold:
 - **Domain + industry** — what world does this product operate in?
 - **Actors** — real roles with real responsibilities. These are scenario and persona seed material.
 - **Governed_by** — regulations and standards (if applicable). These create structural tensions in regulated domains.
-- **Glossary** — domain vocabulary. Scenarios and personas must use these terms, not generic UI words.
 - **Notes body** — extended context, often containing workflow descriptions, pain points, organizational dynamics.
 
+Read `iamu/testability.md` (if present) to enforce execution boundaries:
+- **Reachable surfaces:** Ground candidates in reachable routes. Avoid proposing scenarios for product areas with no navigable surfaces.
+- **Untestable boundaries:** Strictly avoid proposing scenarios in flows documented as untestable (e.g. un-mocked live payment gateways, SMS dispatch, third-party SSO).
+- **Mocks & Fixtures:** Note which candidates require existing database seeds or mock handlers.
+
 ### 2. Load existing coverage
 
 Read existing entities to understand what's already been tested:
@@ -61,46 +65,75 @@ Four entry paths based on `$ARGUMENTS`:
 - **Open-ended** (e.g. `iamu-propose`, `iamu-propose "what's missing?"`) — analyze coverage gaps across both scenarios and persona diversity. Prioritize uncovered capabilities and actors without personas.
 - **Specific tension** (e.g. `iamu-propose "what happens when the safety coordinator disagrees with HR?"`) — use as seed but ground in context. Verify the tension is real (do these actors and dynamics exist in the domain?).
 
-### 4. Present candidates (Comparison Table)
+### 4. Present candidates (Numbered Cards)
 
-Present candidates in a single, high-contrast **Markdown comparison table** fitting the terminal viewport. Do NOT dump long paragraphs, full narratives, or regulatory citations upfront.
+Present candidates as scannable numbered cards. Do NOT use multi-column markdown tables with full prose sentences (they wrap awkwardly and break borders in terminal viewports). Do NOT dump long paragraphs, full narratives, or regulatory citations upfront.
 
 #### A. When proposing Scenarios:
 
-Lead with a one-line summary of existing coverage, then render the table:
-
-```
-Existing coverage: <N> scenarios (<list slugs>). Uncovered areas: <gaps>.
-
-| # | Situation | Role | Core Domain Tension | What It Stress-Tests |
-|---|-----------|------|---------------------|----------------------|
-| 1 | <Short situation name> | <Actor from context> | <1-line human/domain tension> | <What this reveals about the product> |
-| 2 | ... | ... | ... | ... |
-| 3 | ... | ... | ... | ... |
+Lead with existing coverage using clickable links, then render the candidates:
 
-Pick a number (1–3) to draft via iamu-new, or refine (e.g. "make #2 more time-pressured", "none of these — explore <area>").
 ```
+Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Uncovered areas: <gaps>.
+
+1. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
+
+2. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
+
+3. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
+
+**Interactive Candidate Selection:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Which scenario candidate would you like to scaffold?"
+  - Options:
+    1. "[Recommended] Scaffold '<Candidate 1 Title>' (<Actor>)"
+    2. "Scaffold '<Candidate 2 Title>' (<Actor>)"
+    3. "Scaffold '<Candidate 3 Title>' (<Actor>)"
+- Otherwise (in CLI or text-only environments):
+Press Enter to scaffold [1], select 2-3, or describe adjustments:
+(Treat empty Enter as Option 1)
 
 #### B. When proposing Personas:
 
-Lead with existing persona coverage and uncovered roles from `context.yml`:
+Lead with existing persona coverage using clickable links and uncovered roles from `context.yml`:
 
 ```
-Existing personas: <list slugs>. Uncovered roles from context.yml: <roles>.
+Existing personas: [<slug1>](iamu/personas/<slug1>.md), ... Uncovered roles from context.yml: <roles>.
+
+1. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
 
-| # | Persona Candidate | Domain Role | Diagnostic Friction & Biases | Key Expectations & Vocabulary |
-|---|-------------------|-------------|------------------------------|-------------------------------|
-| 1 | <Name> | <Actor role> | <Specific friction triggers, skepticism, and bounce risks> | <Domain terms and spec requirements> |
-| 2 | ... | ... | ... | ... |
-| 3 | ... | ... | ... | ... |
+2. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
 
-Pick a number (1–3) to draft via iamu-new (as a standalone persona or with a scenario), or refine.
+3. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
 ```
 
+**Interactive Persona Selection:**
+- If your environment provides an interactive user-prompt tool (e.g. `ask_question`, `ask_followup_question`), invoke it:
+  - Question: "Which persona would you like to add to the casting panel?"
+  - Options:
+    1. "[Recommended] Add <Name 1> (<Actor role>)"
+    2. "Add <Name 2> (<Actor role>)"
+    3. "Add <Name 3> (<Actor role>)"
+- Otherwise (in CLI or text-only environments):
+Press Enter to add [1], select 2-3, or describe adjustments:
+(Treat empty Enter as Option 1)
+
 Ground rules for generation:
 
 - **Start from the actor's week, not the feature list.** What does this person actually do on a Tuesday? What goes wrong? What requires judgment?
-- **Use domain vocabulary from the glossary.** If the glossary says "skyddsombud" not "safety representative," use "skyddsombud."
+- **Use authentic domain vocabulary.** Speak in the language of the domain and the product UI (e.g., "skyddsombud" rather than generic "safety representative"), avoiding abstract test jargon.
 - **Prefer mundane frequency over dramatic edge cases.** The scenario that happens every week reveals more than the one that happens once a year.
 - **Structural tensions come from the domain, not from product limitations.** A real tension: "the regulation requires immediate reporting but the coordinator handles 3 sites." A fake tension: "the CSV upload has a 50-row limit."
 - **Never mention the product, its UI, its features, or its limitations.** The scenario exists in the domain. The product encounter happens during the walkthrough.
@@ -110,9 +143,9 @@ Ground rules for generation:
 
 ### 5. Selection and Handoff
 
-- **User picks a scenario candidate** → hand off to `iamu-new` with the selected candidate's situation as the intent seed. Provide the full context (actor, regulatory surface, why-interesting) so `iamu-new` can ground its outline generation.
-- **User picks a persona candidate** → hand off to `iamu-new` with candidate profile (name, role, disposition, vocabulary, friction triggers). `iamu-new` can scaffold the persona standalone into `iamu/personas/` or pair them with a situation draft.
-- **User refines** → regenerate or adjust the comparison table, re-applying the philosophy tests.
+- **User picks a scenario candidate (e.g. "1" or Enter)** → Immediately invoke `iamu-new` in **Fast-Path Scenario Mode** passing the selected candidate title, actor, tension, and evaluation checkpoint as structured arguments. Do NOT allow `iamu-new` to restart seed brainstorming. It must present the single Scenario Spec-Sheet directly for instant 1-click persistence.
+- **User picks a persona candidate** → Immediately invoke `iamu-new` in **Standalone Persona Mode** with the candidate's name, role, disposition, and friction triggers to scaffold directly into `iamu/personas/<slug>.md`.
+- **User refines** → regenerate candidates applying the requested adjustments.
 - **User rejects all** → ask what domain area or actor they want to explore. Loop back to step 4.
 
 ## Guidelines