workmagicio/workmagic-agent-plugin

"owner": {     "name": "WorkMagic",     "url": "https://workmagic.io"

"name": "WorkMagic",     "url": "https://workmagic.io"   },

"url": "https://workmagic.io"

"author": {     "name": "WorkMagic",     "url": "https://workmagic.io"

"name": "WorkMagic",     "url": "https://workmagic.io"   },

"url": "https://workmagic.io"

},   "homepage": "https://workmagic.io",   "license": "MIT",

"homepage": "https://workmagic.io",

"license": "MIT",   "privacyPolicyUrl": "https://workmagic.io/privacy",   "keywords": [

"privacyPolicyUrl": "https://workmagic.io/privacy",

| `test_end_date` within 0–30 days before `anomaly_start` | Overlaps anomaly window — very likely the trigger | | `LIFT_PCT` ≈ 0 or very low | Test concluded near-zero incrementality → iDDA cuts weight sharply | | `NC_IROAS` noticeably lowe

| `LIFT_PCT` ≈ 0 or very low | Test concluded near-zero incrementality → iDDA cuts weight sharply | | `NC_IROAS` noticeably lower than previous test | Calibration was pulled down; NC attribution drops with it | | `auto_apply = 1` | Result a

| `NC_IROAS` noticeably lower than previous test | Calibration was pulled down; NC attribution drops with it |

This skill detects NC state, guides configuration when needed in business language, and continues the original query after configuration. **The user should rarely (ideally never) have to leave the chat to set up NC themselves.**

- Dimension is already a built-in field (`ads_platform`, `campaign_name`, `tactic_name`, etc.) → `attribution-data-query` - Dimension is already an NC-derived property the tenant has configured → `attribution-data-query` (just use the prope

- User is asking about NC configuration in general ("how does NC work?") → answer from `database-query-ask` without entering this skill

| `business_term` | Required | User's natural-language label (e.g., "audience", "region", "brand"). Preserve as candidate propertyName — rephrase later if the tenant already has a slightly different name. | | `nc_state` | Detected, not aske

| `nc_state` | Detected, not asked | One of: **A) configured + property exists**, **B) configured + property missing**, **C) not configured at all**. Determined by `naming-convention-list` + `dashboard-metrics-list`. | | `tenantId` | Requir

| `tenantId` | Required for tool calls | Pass to `dashboard-metrics-list` for tenant-specific NC propertyNames. Pass to `naming-convention-list` to read existing rules. |

| `original_query` | Required | The full attribution-data-query intent the user came in with (metric, time range, filters). Preserve so we can pick it up after NC config completes. |

**Step 1: Detect NC state** — two parallel calls:

1. `dashboard-metrics-list` with `tenantId` → list of available propertyNames (built-in + NC-derived) 2. `naming-convention-list` with `tenantId` → existing NC rules (separators, position, property mappings)

2. `naming-convention-list` with `tenantId` → existing NC rules (separators, position, property mappings)

| **State** | **How to detect** | **Next step** | |-|-|-| | **A. Configured + property exists** | Requested term (fuzzy match, case-insensitive) appears in `dashboard-metrics-list` propertyNames | Use the propertyName **exactly as returned 

|-|-|-| | **A. Configured + property exists** | Requested term (fuzzy match, case-insensitive) appears in `dashboard-metrics-list` propertyNames | Use the propertyName **exactly as returned (case-sensitive)** and route to `attribution-data-

| **A. Configured + property exists** | Requested term (fuzzy match, case-insensitive) appears in `dashboard-metrics-list` propertyNames | Use the propertyName **exactly as returned (case-sensitive)** and route to `attribution-data-query`. 

| **B. Configured + property missing** | `naming-convention-list` has existing rules, but the requested term doesn't appear in the propertyName set | Step 2 — add one rule to the existing NC |

| **C. Not configured at all** | `naming-convention-list` returns empty | Step 3 — set up NC from scratch |

**Step 3 [State C]: Set up NC from scratch**

| **Tool** | **Required?** | **Purpose** | |-|-|-| | `database-query-ask` | Required (first) | NC schema patterns + Cube.dev syntax + `ctx` timestamp for any SQL (sample pull + sanity check) |

|-|-|-| | `database-query-ask` | Required (first) | NC schema patterns + Cube.dev syntax + `ctx` timestamp for any SQL (sample pull + sanity check) | | `dashboard-metrics-list` | Required | List propertyNames for this tenant (built-in + NC)

| `database-query-ask` | Required (first) | NC schema patterns + Cube.dev syntax + `ctx` timestamp for any SQL (sample pull + sanity check) |

| `dashboard-metrics-list` | Required | List propertyNames for this tenant (built-in + NC). | | `naming-convention-list` | Required | Read existing NC rules to determine State A / B / C | | `naming-convention-separators-get` | Conditional (

| `naming-convention-list` | Required | Read existing NC rules to determine State A / B / C |

| `naming-convention-separators-get` | Conditional (State C) | Detect what separators the tenant's campaign names use, before proposing a rule | | `naming-convention-create` | Conditional (B + C) | Create NC rule after user confirmation. | 

| `naming-convention-create` | Conditional (B + C) | Create NC rule after user confirmation. |

| `naming-convention-update-or-delete` | Conditional (State B) | Update existing NC ruleset to add the new property |

- **State A (silent path)**: no NC interaction visible to user — just answer the original query

- **One confirmation question max**; never ask multi-question forms - **Promise the follow-through** ("I'll pull the audience-level ROAS you asked for") so user doesn't worry about losing context - **Use the user's term** as the property na

- **Use the user's term** as the property name unless their NC already has a different name for it

2. **Always sanity-check after applying** — if most rows are NULL, surface and adjust; never silently hand off bad data 3. **Never silently substitute a nearby property** — if user asked for "audience" and tenant only has "segment", don't q

3. **Never silently substitute a nearby property** — if user asked for "audience" and tenant only has "segment", don't query "segment" without telling them 4. **Never send user to UI to configure NC themselves** — the skill exists precisely

4. **Never send user to UI to configure NC themselves** — the skill exists precisely so they don't have to

- **Downstream (always)**: `attribution-data-query` — handoff after configuration completes, or directly when State A - **Upstream**: `attribution-intent-clarification` (when the business term itself is ambiguous, e.g., "by region" could me

- **Upstream**: `attribution-intent-clarification` (when the business term itself is ambiguous, e.g., "by region" could mean campaign tag vs sales region) - **Sibling**: `attribution-anomaly-diagnosis` (after slicing by NC property, user ma

- **Sibling**: `attribution-anomaly-diagnosis` (after slicing by NC property, user may ask "why is this segment down?")

## Example A — "ROAS by audience" (State C, NC from scratch)

The first-time experience: a tenant that's never set up NC asks for a query that needs an NC property.

#### Step 1 — Detect NC state

- Call `dashboard-metrics-list` with tenantId. Result: built-in propertyNames only — no "Audience", no "audience", no fuzzy match. - Call `naming-convention-list` with tenantId. Result: **empty** — no existing NC rules.

- Call `naming-convention-list` with tenantId. Result: **empty** — no existing NC rules.

Ask `database-query-ask` for NC schema. Get `ctx`.

#### Step 5 — Apply NC rule

| Campaign names look inconsistent — no clear pattern | Tell the user honestly: "Your campaign names don't follow a consistent pattern, so I can't extract this reliably. Best path: standardize the naming going forward, and we can revisit th

| Most rows resolve to NULL after applying the rule (sanity check fails) | Don't hand off. Surface the failure: "The rule I tried only caught X% of your campaigns. Here are the ones it missed — want me to adjust?" Offer 1-2 alternative inte

| User asks to set up NC without an underlying data question | Route to a general NC setup flow (could be a separate skill or product onboarding); this skill is data-query-driven. Don't run setup steps without a pending query to answer afte

| User wants to remove or rename an existing NC property | Admin-level. Confirm explicitly with extra UX confirmation ("This will affect all dashboards using this property"), then use `naming-convention-update-or-delete`. |

- **Silently substitute a nearby property** — if user asked for "audience" and tenant only has "segment", don't just query "segment" without telling them - **Send the user to the UI to configure NC themselves** — the skill exists precisely 

- **Send the user to the UI to configure NC themselves** — the skill exists precisely so they don't have to. Only escalate to UI if config is genuinely impossible from chat (e.g., needs admin permissions the agent doesn't have).

- **Skip `database-query-ask` before SQL** — required for `ctx` timestamp on both the sample pull and the sanity check - **Treat State A as needing configuration** — if the propertyName already exists, just use it; don't show the user a con

- **Propose all NC properties at once on State C** — focus on the term the user just asked about; other properties can be added later

1. **Brief intro** (1-2 sentences). State B: short, no concept introduction. State C: explain NC in business language.

## NC state routing (detailed)

This is the happy path. The tenant has already configured an NC rule, and the propertyName the user asked for (or a fuzzy match) is in `dashboard-metrics-list` response.

- Use the propertyName **exactly as returned (case-sensitive)** - Hand off directly to `attribution-data-query` - **No NC interaction visible to user** — they just see the data answer to their original ask

- Hand off directly to `attribution-data-query` - **No NC interaction visible to user** — they just see the data answer to their original ask - If the user's term doesn't exactly match (e.g., user says "Region", tenant has "region") — use t

- **No NC interaction visible to user** — they just see the data answer to their original ask

Tenant has existing NC rules but not for the term the user just asked about. They've been through this process before — keep the explanation short.

-- Step 2/3: Pull 5-10 real campaign names to read before proposing an NC rule

-- Step 4: Sanity-check that the new NC property resolves to non-empty values for most rows

**State B (NC exists, this property missing)**:

**State C (NC not configured)**:

| dataset | Required | One of: channel_attribution (by channel) / ads_attribution (by campaign/ad) / creative_attribution (by creative) / order_sales (raw orders, no attribution split). Infer from user phrasing; never ask user to pick a Dat

| metric | Required | Extract from user input. Always call dashboard-metrics-list to validate the field name before using it. Never guess. | | dimension | Required | Validate against dashboard-metrics-list. For ads_attribution / creative_at

| dimension | Required | Validate against dashboard-metrics-list. For ads_attribution / creative_attribution with NC dimensions (Product Group, Asset Type, Creator name, etc.), pass tenantId to fan out tenant-specific propertyNames. |

- Confirm metric / dimension field names exist on the chosen DataSet - For aliases ("POAS", "return on ad spend") → find closest match. If none, ask once. - **For NC dimensions on `ads_attribution` / `creative_attribution`**: pass `tenantId

- **For NC dimensions on `ads_attribution` / `creative_attribution`**: pass `tenantId` to fan out tenant-specific propertyNames (e.g., `Product Group`, `Asset Type`). Use propertyName **exactly as returned (case-sensitive)**.

| dashboard-metrics-list | Required | Validate metric / dimension field names exist on the chosen DataSet. | | database-query-run | Required | Execute the Cube.dev SQL query. | | tenant-list | Optional | Look up tenantId when needed to fan 

| tenant-list | Optional | Look up tenantId when needed to fan out NC dimensions on dashboard-metrics-list. |

- **Use raw warehouse SQL instead of Cube.dev syntax** — `database-query-run` only accepts Cube.dev SQL - **Use `attribution_model` as a SQL column** — the actual dimension is `attr_model_name` - **Hard-code `propertyNames` for NC dimension

- **Use `attribution_model` as a SQL column** — the actual dimension is `attr_model_name` - **Hard-code `propertyNames` for NC dimensions** — they are tenant-specific and case-sensitive; always pass `tenantId` to `dashboard-metrics-list` fi

- **Hard-code `propertyNames` for NC dimensions** — they are tenant-specific and case-sensitive; always pass `tenantId` to `dashboard-metrics-list` first

- **Downstream**: `attribution-data-query` (after resolution, most common) - **Route to instead**: `attribution-anomaly-diagnosis` (for "why" questions), `attribution-model-comparison` (for "X vs Y model" questions), `attribution-edge-routi

- **Sibling**: `attribution-custom-dimension` (when ambiguity is "by <business term>" that needs NC config)

| **Scope** | "How are my ads doing?" | Which channels? Which time window? Compared to what? | | **Comparison** | "Compare last month to this month" | Which metric? Which dimension? Channel-level or campaign-level? | | **Subject** | "Look a

| **Subject** | "Look at my best campaign" | Best by what (ROAS / sales / NC orders)? In what window? |

- ❌ Blaming the channel (“Meta underperformed”) — describe what the data shows - ❌ Owning cross-channel allocation decisions in prose — hand off to MBO - ❌ Inventing fields not returned by the readout tool (e.g. fabricating new-customer cou

- ❌ Inventing fields not returned by the readout tool (e.g. fabricating new-customer counts when only NC orders are present, or attribution-model breakdowns that are out of scope here)

- ❌ Saying “cut Meta” — always “reallocate toward higher-mROAS” / “shift budget” - ❌ Evaluative adjectives (strong, solid, weak, meaningful, substantial, remarkable, considerable, robust, compelling, impressive). Use neutral descriptors tie

- ❌ Calling NC iROAS < \$1 a problem unprompted — it’s normal. First-purchase revenue typically doesn’t cover full CAC.

- **Frame stakes in dollars where possible.** Dollar amounts beat bare percentages where it fits. “\$11k incremental sales on \$11k ad spend” lands harder than “13.5% lift.” - **Acknowledge what wasn’t measured.** Meta-only test? Don’t spec

- **Acknowledge what wasn’t measured.** Meta-only test? Don’t speculate about Google or TikTok. Amazon halo not in scope? Say so when the user asks decision questions. - **NC ROAS / NC iROAS < \$1.00 is normal.** First-purchase revenue typi

- **NC ROAS / NC iROAS < \$1.00 is normal.** First-purchase revenue typically doesn’t cover full CAC. Don’t flag it as a problem unless the user explicitly framed it that way.

|-|-| | Per-order count | ≥ 1,000 → 1,234; < 1,000 → integer 146 | | ROAS / iROAS / NC iROAS values | \$X.XX always 2 decimals — \$2.10, \$0.58 |

| Per-order count | ≥ 1,000 → 1,234; < 1,000 → integer 146 | | ROAS / iROAS / NC iROAS values | \$X.XX always 2 decimals — \$2.10, \$0.58 | | Percentages | X.X% one decimal — 13.5%, 0.2% |

| ROAS / iROAS / NC iROAS values | \$X.XX always 2 decimals — \$2.10, \$0.58 |

*"Scenario created — \[Open in MBO →\](https://app.workmagic.io/...). Recommended allocation: Meta \$310K (+12% vs baseline), Google \$190K (−15%). Expected sales lift: \~+\$240K vs reference allocation. Google_Brand_Search and Meta_Retarge

**Reference docs**: [Media Budget Optimizer knowledge base](https://mc10lxkn1j7.sg.larksuite.com/wiki/R59swl3L2iW4BNkGq2Kle3jdgeb) — Reading Your Results + FAQ.