# Product-user prompts → Impact Nova actions

Product and planning users **do not** say "scaffold Vite" or "use Layout from impact-nova/layout". They describe **workflows, grids, and prototypes** in business language. The MCP agent must translate that intent automatically.

Real examples (from planning/retail sessions):

- *"Create a workflow where users edit sales KPIs and dependent metrics update…"*
- *"Create a working prototype — show a grid with KPIs for 2 months and SKUs in rows…"*
- *"Make it contextual to how my product looks — sidebar, breadcrumbs, filter chips, Excel-like grid"*
- *"As a Planning User I want to trigger receipt recalculation after editing Sales Units…"* (user story + acceptance criteria)
- *"Add Sales Planning and Receipt Planning modes on top — when user switches, recalculate and highlight cells"*

**None of these mention Vite, React, or Impact Nova.** The agent must infer the stack.

---

## Agent decision tree

```
User message
    │
    ├─ Describes app shell (sidebar, header, breadcrumbs, filters) OR planning/dashboard tool OR "like Item Smart"
    │     └─ Greenfield (empty folder / "new app" / "prototype from scratch")?
    │           YES → scaffold_impact_nova_app FIRST, then implement feature
    │           NO  → use existing project Layout; add route/page only
    │
    ├─ Mentions grid / KPIs / SKUs / rows & columns / Excel-like / planning
    │     └─ DataTable from impact-nova/data-table (NOT raw HTML table, NOT plain AG Grid)
    │        + resource impact-nova://ag-grid-rules
    │
    ├─ Workflow modes (Sales Planning / Inventory / Receipts)
    │     └─ **Inside** `DataTableToolbar` → `ButtonGroup` (`impact-nova/button-group`)
    │        **Outside** table card (page-level datasets) → `Tabs variant="box"` (`impact-nova/tabs`)
    │        Auto-recalc on mode switch = state + DataTable API refresh
    │
    ├─ Filter chips (ACCESSORY, plan period, etc.)
    │     └─ FilterStrip from impact-nova/filter-strip
    │
    ├─ User story + acceptance criteria (buttons, states, tooltips)
    │     └─ Parse into: Button states, Toast, Alert banner, disabled/enabled matrix
    │
    ├─ "HTML artifact" / "standalone html file" ONLY
    │     └─ Raw HTML allowed (user explicitly asked)
    │
    └─ Default for "prototype" / "working demo"
          └─ Impact Nova React app (scaffolded), NOT a single .html file
```

---

## What NOT to do (common mistakes)

| Product user said | Wrong agent response | Correct response |
|-------------------|---------------------|------------------|
| "Create a planning grid prototype" | Single `planning_prototype.html` with inline React | `scaffold_impact_nova_app` → DataTable page + Layout |
| "Make it look like our product" | Generic Bootstrap/MUI layout | Layout + Sidebar + Header + BreadcrumbHeader + FilterStrip (Item Smart pattern) |
| "Grid with KPIs per month" | HTML `<table>` | DataTable with column groups (AG Grid ColGroupDef) |
| "Highlight recalculated cells" | CSS hack in HTML | AG Grid `cellClassRules` or custom cell renderer |
| "Success toast on save" | `alert()` | `toast()` + Toaster from impact-nova |
| "Stepper: Sales → Inventory → Receipts" | Custom div stepper | `ButtonGroup` inside `DataTableToolbar`; `Tabs variant="box"` only for page-level table switching |

---

## Intent keywords → MCP tools (call in order)

| User language | Tools / resources |
|---------------|-------------------|
| New app, prototype, demo, "from scratch", empty workspace | **1.** `scaffold_impact_nova_app` **2.** implement feature |
| Screenshot, Figma URL, or "looks like our app" | `impact-nova://ia-design-language` + `suggest_components_for_ui` + `get_real_world_patterns` topic=layout |
| Grid, KPIs, SKUs, planning, Excel-like | `get_real_world_patterns` topic=data-table + `impact-nova://ag-grid-rules` |
| Workflow modes inside toolbar vs page tabs | `get_component` ButtonGroup (toolbar) / Tabs `variant="box"` (outside table) |
| Filters, chips, plan period | `get_real_world_patterns` topic=filter |
| Charts, trends | `get_real_world_patterns` topic=chart |
| User story / acceptance criteria | `generate_page` with full story pasted; extract button states |
| Any greenfield dashboard | `impact-nova://layout` (architecture after scaffold) |

---

## Scaffold-then-build pattern (recommended)

When a product user describes a **full-screen tool** (planning, reporting, admin):

**Read `impact-nova://product-quality-bar` and `impact-nova://ia-design-language` first** — Item Smart / IA Figma parity is mandatory for planning.

### Phase A — Landing (no filters yet)

- `EmptyContainer` + "Select filter" button
- Breadcrumb only — **no grid, no filter strip**

### Phase B — Filter selection

- `FilterPanel` + `FilterPanelSidebar` (Product, Channels, Plan Period, Saved Filters)
- Footer: Cancel · Save filter · Apply filters

### Phase C — Workspace (after Apply)

### Step 1 — Scaffold (silent to user unless they care)

```
scaffold_impact_nova_app({
  projectName: "planning-prototype",  // derive from feature name
  skipInstall: false
})
```

User never needs to say this. Agent infers from "create a prototype" + no existing codebase.

### Step 2 — Apply recipe from prompt (do not hand-build pages in template)

```typescript
scaffold_impact_nova_app({
  projectName: "retail-planning-prototype",
  modules: [{
    recipe: "filtered-workspace",
    slug: "retail-planning",
    title: "Retail Planning",
  }],
})
```

Base template is **shell only**. The `filtered-workspace` recipe adds `src/modules/<slug>/` with empty → FilterPanel → workspace.

- **Retail 3-step** (`chat_history.txt`): set `workflowProfile: "retail-three-step"` in `module.config.ts` — Sales / Inventory / Receipts tabs, auto-recalc on switch.
- **Item Smart receipt** (`chat_history (1).txt`): set `workflowProfile: "item-smart-receipt"` — Preview / Save + pending receipt warning.

Replace mock data in `utils/sample-data.ts` and filter constants for the user's domain.

### Step 3 — Customize workspace (see product-quality-bar)

```tsx
// Phase A: !filtersApplied → EmptyContainer + Select filter
// Phase B: FilterPanel (sidebar tabs + Apply filters)
// Phase C: filtersApplied →
<>
  <BreadcrumbHeader>
    <Hide filters /> <Hide KPIs />
  </BreadcrumbHeader>
  <FilterStrip onAllFiltersClick={openFilterPanel} />
  <Accordion>KPI Summary</Accordion>
  <DataTable className="bg-white rounded-md">
    <DataTableSheet>
      <DataTableToolbar>
        <Tabs>Sales | Inventory | Receipts</Tabs>
        <DataTableViewMenu />  {/* ⋮ → Table settings, Density, Expand */}
      </DataTableToolbar>
      <DataTableSheetContent>Columns + Format</DataTableSheetContent>
      <DataTableContent columnDefs={...} />
    </DataTableSheet>
  </DataTable>
</>
```

### Step 4 — Wire behaviors from user story

- Button enable/disable → derive from edit state (acceptance criteria table)
- Pending receipt cells → `cellClassRules` + blurred style token
- Tab switch auto-recalc → `onValueChange` on Tabs + flash cells via grid API
- Save → `toast({ title: 'Saved' })`

---

## Mapping: chat history patterns → components

### Pattern A — Multi-workflow planning grid (Arhaus-style)

User: grid + SKUs + months + KPI groups + workflow buttons + cell highlights

| UI piece | Impact Nova |
|----------|-------------|
| App chrome | Layout + Sidebar + Header |
| Workflow switcher | Tabs or toolbar Buttons |
| KPI grid | DataTable + grouped columnDefs |
| Editable cells | AG Grid `editable: true` on specific columns |
| Recalc highlight | cellClassRules / custom renderer |
| Complete workflow | Toast |

### Pattern B — Item Smart receipt flow (user story)

User: Generate Receipts, Save Changes, stale cells, tooltips, atomic save

| UI piece | Impact Nova |
|----------|-------------|
| Toolbar actions | Button + ButtonGroup in breadcrumb bar |
| Stale EOP/BOP/Receipts | cellRenderer + muted/blur token class |
| Warning banner | Alert below FilterStrip |
| Loading on action | Button `loading` prop or Loader |
| Success | toast() |
| Product chrome | Layout + FilterStrip (chips) + BreadcrumbHeader |

### Pattern C — Screenshot "make it like our product"

User attaches screenshot of Item Smart

1. `suggest_components_for_ui` with description from image
2. Do **not** rebuild sidebar from scratch — use scaffolded `AppSidebar` / `AppHeader`
3. Match: FilterStrip, DataTable toolbar, breadcrumb, navy sidebar (default Sidebar theme)

---

## Sample agent handling

**User:** *"Create a working prototype for receipt planning. Show a grid with KPIs for 2 months and SKUs in rows. Buttons for sales, inventory, and receipt planning. Highlight dependent KPIs when recalculated. Toast on workflow complete."*

**Agent plan:**

1. Check workspace — if no `package.json` with impact-nova → `scaffold_impact_nova_app({ projectName: "receipt-planning-prototype" })`
2. Open `/planning` — extend `planning-page.tsx` / sample data for the user's KPIs and workflows (scaffold already has 3-phase chrome + split grid)
3. Mock row data: adjust `planning-sample-data.ts` (SKUs × months × KPI column groups)
4. Implement workflow switch + derive() recalc (plain TS, not new hook per KPI)
5. `npm run dev` — give user localhost URL

**Do not** output `planning_prototype.html`.

---

**User:** *"Here's a user story with acceptance criteria for Generate Receipts and Save Changes… design intuitive workflow."*

**Agent plan:**

1. If greenfield → scaffold first
2. Parse acceptance criteria → button state matrix (document in code comments)
3. Build Items-style page with FilterStrip + DataTable + toolbar Buttons
4. Implement states: disabled/enabled/loading per criteria table
5. Use Alert for "Receipt calculation pending" banner

---

## Prompts to register (MCP)

Use prompt **`build-product-prototype`** when the user message looks like product language (workflow, user story, prototype, grid, KPIs, planning, "make it like our app").

Never require the user to say "scaffold" or "Impact Nova".

---

## Publish note

**`create-impact-nova@^1.4.9`** is on npm. Scaffold auto-detects `impact-nova` dependency (npm `^2.5.10` + AG Grid `36.0.1` vs monorepo `file:`). Override: CLI `--from-npm` / `--link-monorepo` · MCP `usePublishedPackages`.