callbacks brand

# Artemis Data Integrity Hub Dashboard Workflow And AI Context

This document explains the monthly data refresh dashboard in business terms and implementation terms. It is meant to be used as working context for writing user stories, AI training prompts, and Artemis AI response guidance.

## 1. Dashboard Purpose

The Artemis Data Integrity Hub is a monthly refresh quality dashboard. It helps a data quality reviewer answer four questions:

1. Is data present for the selected market, brand, source, metric, customer, pack, or territory?
2. Is the data passing the expected quality checks?
3. Which source, brand, metric, customer, pack group, or media metric is driving the issue?
4. What should the reviewer do next: inspect trend, approve, raise issue, notify owner, or download evidence?

The dashboard has four main monthly refresh pages:

1. Portfolio view
2. Overall summary (Brand)
3. Source level summary
4. Metric level summary

The pages are connected as a user journey:

1. Portfolio view identifies weak brand/metric cells across the portfolio.
2. Overall summary gives market/brand level health through completion, compliance, and stability donuts.
3. Source level summary shows which data source is weak.
4. Metric level summary shows exact metric-level failures, failed check counts, validation status, and trend evidence.

## 2. Common Dashboard Terms

### Market / Country

The selected geography. In the UI the markets are shown as names such as `Country 1`, `Country 2`, and `Country 3`.

The implementation maps these markets to market-specific fact tables and SQL:

- `Country 2`: GB SQL and GB fact tables.
- `Country 1`: TR SQL and TR fact tables.
- `Country 3`: BR SQL and BR fact tables.

### Category

The product category selected in global filters. It narrows the brands and metrics in scope where the page uses category filtering.

### Brand

The selected product brand. On portfolio heatmaps, brand is usually the first visible grouping. On other pages, brand can be part of the global filter and title.

### Source

The upstream data source, such as `MDL`, `MPM`, `Nielsen MPM`, `Nielsen`, `Nielsen IQ`, `Global NSR`, `eMMM`, and others.

Source matters because not every source supports every check:

- `MDL` and `eMMM` commonly include media-specific checks such as CPM, population, and operational dual presence.
- `MPM`, `Nielsen`, `Nielsen IQ`, `Nielsen MPM`, and `Global NSR` commonly use launch/de-list checks.
- Some excluded sources such as `Metadata`, `Modeling team`, `Beach`, and `Excite` are filtered out from source cards.

### Metric

The business measure being checked. Examples:

- `paid_media_digital_social_meta_impressions`
- `paid_media_digital_social_other_spend_usd`
- `average_selling_price_usd`
- `comp_price_per_uc`
- `outcome_metric_sell_in_unit_cases`

Metric names may be shown in display format by replacing underscores with spaces and title-casing.

### Customer

The customer account or customer identifier used for granular drilldown. In `Country 1` and `Country 2`, non-media portfolio detail often drills from brand/metric into customer and pack group.

### Pack / Pack Group

The pack identifier or display group. It is used with customer for granular drilldown such as `Customer x Pack`.

### Territory

For `Country 3`, the granular level can be territory rather than customer/pack.

### Media View

Portfolio view toggle mode for media metrics. In media view:

- The upper heatmap groups by brand and a media metric grouping such as L3.
- The lower detail heatmap shows the original metric under the selected media grouping.
- Trend modal matching must use brand, source, selected grouped metric, and original metric where available.

### Non-Media View

Portfolio view toggle mode for non-media metrics. In non-media view:

- The upper heatmap groups by brand and metric.
- The lower detail heatmap drills into customer/pack or territory when those details exist.
- If the source has no lower granular level, the upper heatmap tile can be the most granular clickable entity.

### Current Period

The selected timeframe in the local filter, for example `January 2026`.

Internally, this becomes:

- `cur0`: first day of the selected month.
- `cur1`: first day of the following month.

Example: `January 2026` means `cur0 = 2026-01-01`, `cur1 = 2026-02-01`.

### Reference Period

The comparison period selected in `Compare with`.

Supported options:

- `previous_month`: compares current month against the immediately prior month.
- `same_month_last_year`: compares current month against the same month in the previous year.
- `last_3_months`: compares current month against the previous three-month window.

The dashboard displays changes as:

```text
change = current score - reference score
```

This is a percentage-point change for percentage scores.

### Latest Score

The current-period score for the row, card, tile, or donut.

### Change vs Reference Period

Difference between latest score and reference-period score.

```text
change_vs_reference = current_score - reference_score
```

Positive change is displayed as an upward change. Negative change is displayed as a downward change.

### Null / Blank / Not Applicable

If a check is not applicable, the score is left blank or null. Null checks are excluded from compliance averages. Blank values do not count as failed checks.

### RAG / Color Rules

Different components use slightly different color logic:

- Portfolio heatmap tiles: green when value is `>= 100`, red when value is `< 100`, grey when null.
- Metric-level grid score cells: green when the score is exactly/full `100`, red when below `100`, grey/blank when null.
- KPI cards and donut gauges: green above `70`, amber from `40` to `70`, red below `40`.
- Stability table: green when stability is `>= 70%`, amber from `40%` to `70%`, red below `40%`.

## 3. Core Metric Definitions And Calculations

### Completion

Business meaning:

Completion measures whether expected data is present for the selected scope.

Raw field:

```text
completion_flag
```

Typical raw values:

- `1`: data is present / complete.
- `0`: data is missing / incomplete.
- `null`: not applicable or unavailable.

Calculation:

```text
completion_score = AVG(completion_flag) * 100
```

Examples:

- If 10 expected rows exist and all 10 have `completion_flag = 1`, completion is `100%`.
- If 6 out of 10 rows have `completion_flag = 1`, completion is `60%`.
- Null values are naturally ignored by SQL `AVG`.

Where shown:

- Portfolio heatmap when KPI = `Completion`.
- Overall completion donut.
- Source card completion.
- Metric-level `Completion` grid group and KPI card.

### Compliance

Business meaning:

Compliance measures whether the available data passes applicable quality checks. It is not only data presence. It is the average quality score across the applicable checks for the selected scope.

Main check components:

- Data type compliance
- Outlier compliance
- Population compliance
- CPM compliance
- Operational dual presence
- Launch/de-list compliance

Generic formula:

```text
compliance_score =
  AVG(
    data_type_score,
    outlier_score,
    population_score,
    cpm_score,
    operational_dual_score,
    launch_delist_score
  )
```

Only non-null applicable checks are included in the denominator.

Implementation pattern:

```sql
SELECT AVG(val)
FROM (VALUES
  (data_type_check_result * 100),
  (outlier_check * 100),
  (population_check_flag * 100),
  (cpm_flag * 100),
  (operational_dual_score),
  (delist_score)
) t(val)
WHERE val IS NOT NULL
```

Important applicability notes:

- Spend metrics ending in `_spend_usd` do not use population check, so population is blank/null for those metrics.
- Operational dual presence is mostly relevant for sources such as `MDL` and `eMMM`.
- Launch/de-list is mostly relevant for sources such as `MPM`, `Nielsen`, `Nielsen IQ`, `Nielsen MPM`, and `Global NSR`.

Where shown:

- Portfolio heatmap when KPI = `Compliance`.
- Overall compliance donut.
- Source card compliance.
- Metric-level `Compliance` grid group and KPI card.

### Data Type Compliance

Business meaning:

Checks whether the values have the expected type or format.

Raw field:

```text
data_type_check_result
```

Calculation:

```text
data_type_compliance = AVG(data_type_check_result) * 100
```

Interpretation:

- `100%`: all checked rows have the expected type.
- `<100%`: at least one checked row failed the expected type.

Metric-level column:

```text
Check1_2 pass
```

### Outlier Compliance

Business meaning:

Checks whether metric values are inside expected outlier bounds.

Raw field:

```text
outlier_check
```

Calculation:

```text
outlier_compliance = AVG(outlier_check) * 100
```

Trend modal:

The modal shows:

- metric weekly trend line,
- upper outlier bound,
- lower outlier bound,
- shaded reference/current period context.

Metric-level column:

```text
Check2 pass
```

### Population Compliance

Business meaning:

Checks whether metrics that can be validated against population are plausible.

Raw field:

```text
population_check_flag
```

Calculation:

```text
population_compliance = AVG(population_check_flag) * 100
```

Applicability:

- Not used for spend metrics ending in `_spend_usd`.
- Often relevant for media impression metrics.

### CPM Compliance

Business meaning:

Checks whether cost per thousand impressions is within an acceptable range.

Raw field:

```text
cpm_flag
```

Calculation:

```text
cpm_compliance = AVG(cpm_flag) * 100
```

Trend modal:

For media metrics, CPM may be shown as an additional line or contextual metric.

### Operational Dual Presence

Business meaning:

Checks whether paired operational metrics remain consistently present between the reference period and current period. It is meant to catch a situation where a paired metric existed before but is missing now.

Raw field:

```text
op_dual_pres_flag
```

Strict failure logic:

```text
operational_dual = Failed
if all reference rows passed AND all current rows failed

otherwise operational_dual = Passed
```

Score conversion:

```text
Passed -> 100
Failed -> 0
null -> not applicable
```

Implementation detail:

The logic intentionally uses strict all-row behavior. It only marks failure when the reference period fully passed and the current period fully failed. If even one valid current row passes, the metric is treated as passed.

### Launch / De-list Compliance

Business meaning:

Checks whether a brand/metric remained consistently present between periods, or whether it appears to be newly launched or de-listed.

Raw fields:

```text
not_de_list_flag
non_de_list_final
```

Status logic:

```text
if current is null:
    blank / not applicable
elif reference > 0 and current == 0:
    Delist
elif reference == 0 and current > 0:
    Launched
else:
    Present
```

Metric/source level score:

```text
launch_delist_score =
  count(Present) / count(Present, Delist, Launched) * 100
```

Portfolio row-level score can also use a continuous score:

```text
if no current or no reference:
    null
elif reference > 0 and current == 0:
    0
elif reference == 0 and current > 0:
    0
elif reference > 0:
    min(current / reference, 1) * 100
else:
    100
```

Interpretation:

- `Present`: stable and compliant.
- `Delist`: existed in reference period but disappeared in current period.
- `Launched`: did not exist in reference period but appears in current period.

### Stability

Business meaning:

Stability compares the latest restated historical data with the previous dataset version. It answers: "Did the historical values change after refresh?"

Raw stability comparison fields:

```text
value_a_r2 = previous dataset / historical value
value_b_r2 = latest restated value
flag       = stable/unstable indicator in the combined stability table
```

Overall stability donut:

```text
stability = AVG(flag) * 100
```

Metric-level stability table:

1. Compare latest restated value vs previous dataset value.
2. A row is unstable if one value is null and the other is not, or if both are present but rounded values differ.
3. Collapse to `metric x brand x week`.
4. A `metric x brand x week` is unstable if any underlying source/customer/pack slice changed.
5. Calculate:

```text
stability = stable_instances / total_instances
```

The modal table shows:

- Metric
- Unstable brands
- Stability
- Stable weeks
- Total weeks

The stability chart shows two lines:

- Previous dataset version
- Latest restated data

It highlights unstable weeks when there is a presence mismatch or value deviation.

## 4. Portfolio View

Route:

```text
/portfolio-view
```

Purpose:

Portfolio view is the first scanning page. It shows a heatmap of quality by brand and metric so the user can immediately see weak cells.

### Main UI Elements

1. Global filter area
   - Country/market filter.
   - Apply and reset buttons.

2. Artemis AI Insight panel
   - Summarizes the current page.
   - Calls out weakest brand/metric/source/KPI combination.
   - Gives a recommended next action.

3. Page title
   - Format:

```text
Portfolio view | <Media/Non media> | <Country> | <Timeframe> | <Source> | <KPI>
```

4. Media / non-media toggle
   - Switches the grouping logic.
   - Media view shows media metric hierarchy.
   - Non-media view shows normal business metric hierarchy.

5. Local filters
   - Timeframe
   - Source
   - KPI

6. Legend
   - Green = `100%`
   - Red = `<100%`

7. Upper heatmap
   - Brand headers.
   - Metric tiles below each brand.
   - Each tile shows a score.

8. Metric detail section
   - Shows lower granular tiles for the selected brand/metric.
   - Non-media: usually `Customer x Pack`.
   - Country 3: territory.
   - Media: original media metrics under the selected grouped media metric.

9. Trend modal
   - Opens only when a clicked heatmap/detail tile can be matched to trend data.
   - If no matching metric/customer/pack/territory/original metric exists, no modal should open.

### Portfolio View Data Flow

1. User selects country, timeframe, source, KPI, and media toggle.
2. Dashboard loads source/market data through `load_brand_view_data`.
3. Data is mapped by `prepare_heatmap_data`.
4. Top heatmap is rendered by `build_category_brand_heatmap`.
5. Clicking a top heatmap tile updates selected `brand|metric`.
6. Detail heatmap is rendered by `build_detail_heatmap`.
7. Clicking a valid granular tile opens the trend modal when a matching trend dataset exists.

### Portfolio KPI Mapping

KPI dropdown values map to data columns:

| KPI | Source field |
| --- | --- |
| Completion | `completion_flag` |
| Data type check | `data_type_check_result` |
| Outlier check | `outlier_check` |
| Population check | `population_check_flag` |
| CPM check | `cpm_flag` |
| Operational dual presence | `op_dual_score` |
| Launch/Delist check | `delist_score` |
| Compliance | `compliance_score` |

Percent conversion:

- `completion_flag`, `data_type_check_result`, `outlier_check`, `population_check_flag`, and `cpm_flag` are multiplied by `100`.
- `compliance_score`, `op_dual_score`, and `delist_score` are already percent-like scores.

Volume KPI special cases:

| Market | KPI label | Metric | Source |
| --- | --- | --- | --- |
| Country 1 | Sell-in unit case | `outcome_metric_sell_in_unit_cases` | `Global NSR` |
| Country 2 | Sell-in unit case | `outcome_metric_sell_in_unit_cases` | `Global NSR` |
| Country 3 | Volume in uc | `volume_in_uc` | `Nielsen` |

Volume KPIs use `latest_val` or an equivalent value column and aggregate by sum, not average.

### Portfolio Heatmap Grouping

Level definitions:

| Level | Non-media view | Media view |
| --- | --- | --- |
| Level1 | Brand | Brand |
| Level2 | Metric | Media grouped metric, usually L3 |
| Level3 | Customer or territory | Original metric |
| Level4 | Pack group | blank |

Non-media for Country 1/Country 2:

```text
Level3 = customer_name or customer_id
Level4 = pack_group_name or pack_id
detail label = Customer x Pack
```

Non-media for Country 3:

```text
Level3 = territory_id
Level4 = blank
```

Media view:

```text
Level2 = grouped media metric
Level3 = original_metric
Level4 = blank
```

### Portfolio Aggregation Logic

Normal average KPIs:

```text
tile_value = mean(value)
```

Volume KPIs:

```text
tile_value = sum(value)
```

Operational dual presence:

```text
tile_value = 0 if all valid op_dual_score values are 0
tile_value = 100 if any valid op_dual_score value is > 0
tile_value = null if no valid values
```

Compliance:

Compliance is recalculated from available check values when check columns are present:

```text
tile_compliance =
  AVG(
    data_type_score,
    outlier_score,
    population_score,
    cpm_score,
    operational_dual_score,
    launch_delist_score
  )
```

Brand header aggregation:

- Media view: average of child tile values.
- Non-media compliance and operational dual: minimum of child metric tiles so a bad metric is visible at the brand header.
- Other average KPIs: average of child metric tiles.
- Volume KPIs: sum of child metric tiles.

### Portfolio Click And Modal Behavior

Expected click behavior:

1. User clicks an upper heatmap tile.
2. The selected brand/metric is highlighted.
3. If a lower metric detail exists, the lower detail section appears.
4. For granular trend modal, user clicks the lower detail tile.
5. If the source has no lower metric detail, the upper tile may be the most granular level and can open the modal if trend data matches.
6. For media view, modal matching must work from lower metric detail boxes.
7. The modal title should include:

```text
<Metric name> | Source: <Source>
Brand: <Brand>
Customer: <Customer, if available>
Pack group: <Pack group, if available>
Territory: <Territory, if available>
```

No modal should open when required matching context is missing.

### Portfolio AI Context

Artemis AI should answer portfolio questions using:

- selected market/country,
- selected timeframe,
- selected source,
- selected KPI,
- media/non-media mode,
- selected brand/metric if any,
- worst cells,
- number of full `100` cells,
- number of below-100 cells,
- overall average or total for volume KPIs.

Good AI response pattern:

```text
For <Country> in <Timeframe>, Portfolio View is showing <KPI> for <Source>.
The weakest cell is <Brand x Metric> at <score>.
The selected brand has <x> metrics below 100 and <y> metrics at 100.
Next step: click the cell, inspect the metric detail tiles, then open the trend modal for the matching customer/pack or original media metric.
```

## 5. Overall Summary Page

Route:

```text
/monthly-refresh/overall-refresh
```

Purpose:

Overall summary gives a market/brand-level health view for the monthly refresh. It compresses the page into three main questions:

1. Is data complete?
2. Is data compliant?
3. Is restated historical data stable?

### Main UI Elements

1. Page title
   - Format:

```text
Overall summary | <Brand> | <Timeframe> | <Country>
```

2. Local filters
   - Timeframe
   - Compare with

3. Completion donut
   - Current completion percentage.
   - Delta against reference period.

4. Compliance donut
   - Current compliance percentage.
   - Delta against reference period.

5. Stability donut
   - Current stability percentage.
   - Clickable. Opens stability modal.

6. Stability modal
   - Filter dropdowns: Source, Metric, Brand, Customer, Pack.
   - Metric stability grid.
   - Stability trend chart.
   - Download all stability data or selected metric chart data.

### Overall Completion Calculation

At country/brand scope:

```text
overall_completion = AVG(completion_flag) * 100
```

Current and reference are calculated over the relevant date windows:

```text
completion_change = completion_now - completion_reference
```

### Overall Compliance Calculation

The page first calculates source/month compliance using applicable check scores, then rolls up to overall country compliance.

Source/month compliance:

```text
source_compliance =
  AVG(
    data_type_score,
    outlier_score,
    population_score,
    cpm_score,
    launch_delist_score,
    operational_dual_score when applicable
  )
```

Country/overall compliance:

```text
overall_compliance = AVG(source_compliance)
```

Reference change:

```text
compliance_change = compliance_now - compliance_reference
```

### Overall Stability Calculation

Overall stability donut uses:

```text
stability = AVG(flag) * 100
```

The stability data is filtered to:

- selected market,
- selected brand IDs,
- dates before the market cutoff month.

For Country 3, the current implementation sets stability to `0` where the SQL fallback is not enabled.

### Stability Modal Table Calculation

The modal table calculates stability by metric:

```text
total_instances = count(metric x brand x week instances)
stable_instances = count(instances where latest restated value equals previous dataset value)
unstable_instances = count(instances where values differ or one side is missing)
stability = stable_instances / total_instances
```

Unstable brands:

```text
brands with at least one unstable metric x week instance
```

### Stability Trend Chart

The chart compares:

- previous dataset version,
- latest restated data.

Unstable weeks are highlighted when:

```text
latest value is present and historical is missing
OR historical is present and latest is missing
OR absolute difference > 0.01
OR percentage difference > 0.2%
```

### Overall AI Context

Artemis AI should answer overall-summary questions using:

- market,
- brand list,
- category list,
- timeframe,
- compare-with period,
- completion current/reference/change,
- compliance current/reference/change,
- stability current score,
- stability modal details if user is looking at the modal.

Good AI response pattern:

```text
For <Brand> in <Country> during <Timeframe>, completion is <x>%,
which is <up/down/no change> by <delta> percentage points versus <reference>.
Compliance is <y>% with <delta>.
Stability is <z>%, so the next useful check is the stability modal if the user wants to identify unstable metrics.
```

## 6. Source Level Summary Page

Route:

```text
/monthly-refresh/source-level
```

Purpose:

Source level summary shows which source is driving data quality issues. It is the bridge from overall health to metric-level investigation.

### Main UI Elements

1. Page title
   - Format:

```text
Source level summary | <Brand> | <Timeframe> | <Country>
```

2. Local filters
   - Timeframe
   - Compare with

3. Source card carousel
   - Each card represents one source.
   - Cards are sorted by priority source list first, then other sources alphabetically.

4. Source card fields
   - Source name.
   - Selected period.
   - Reference period.
   - Metric count.
   - Completion score.
   - Completion delta.
   - Compliance score.
   - Compliance delta.
   - Notify button for high-priority sources.
   - Download button.

5. Click behavior
   - Clicking a source card stores the selected source and navigates to metric-level summary.

### Source Card Calculation

For each source:

```text
metric_count_curr = count(distinct metric in current period)
metric_count_prev = count(distinct metric in reference period)
completion_curr = AVG(completion_flag current) * 100
completion_prev = AVG(completion_flag reference) * 100
completion_delta = completion_curr - completion_prev
compliance_curr = source compliance in current period
compliance_prev = source compliance in reference period
compliance_delta = compliance_curr - compliance_prev
```

Source compliance uses the same applicable-check logic:

```text
source_compliance =
  AVG(
    data_type_score,
    outlier_score,
    population_score,
    cpm_score,
    launch_delist_score,
    operational_dual_score when applicable
  )
```

### Source Priority

High-priority and preferred ordering includes:

```text
MDL
Nielsen
Nielsen IQ
CCEP
Nielsen MPM
CCI
MPM
Bottler
eMMM
Nielsen Competitive
Global NSR
iRED
Nielsen IQ CP
Pathmatics
S&P Global
Sprinklr
Weather Trends 360
```

Excluded sources:

```text
Metadata
Modeling team
Beach
Excite
```

### Source To Metric-Level Journey

1. User reviews source cards.
2. User identifies a weak source by low completion or compliance.
3. User clicks that source card.
4. Dashboard writes the selected source to the bridge context.
5. Metric-level summary opens with that source preselected.
6. User reviews exact failed metrics and trend evidence.

### Source AI Context

Artemis AI should answer source-level questions using:

- selected market/country,
- selected brand/category,
- selected timeframe,
- compare-with period,
- source list,
- metric count per source,
- completion current/reference/change,
- compliance current/reference/change,
- lowest completion source,
- lowest compliance source,
- largest negative delta.

Good AI response pattern:

```text
The weakest source for <Country> in <Timeframe> is <Source>.
It has <metric_count> metrics, completion of <x>% and compliance of <y>%.
Compared with <reference>, completion moved by <delta1> percentage points and compliance moved by <delta2>.
Next step: open Metric Level Summary for <Source> and sort by failed checks.
```

## 7. Metric Level Summary Page

Route:

```text
/monthly-refresh/metric-level
```

Purpose:

Metric level summary is the action page. It shows exact failed metrics, the checks that failed, trend evidence, and approval/issue workflow controls.

### Main UI Elements

1. Page title
   - Format:

```text
Metric level summary | <Source> | <Brand> | <Timeframe> | <Country>
```

2. Local filters
   - Timeframe
   - Compare with
   - Source
   - Customer / Pack where applicable
   - Territory where applicable

3. KPI cards
   - Overall completion
   - Data type compliance
   - Outlier compliance
   - Conditional cards:
     - Population compliance
     - CPM compliance
     - Operational dual presence
     - Launch/de-list compliance

4. Metric AG Grid
   - Approval / validation status
   - Metric name
   - Trend button
   - Number of failed checks
   - Completion latest score
   - Completion change vs reference
   - Compliance latest score
   - Compliance change vs reference
   - Check-level columns

5. Bulk action footer
   - Appears when rows are selected.
   - Download, approve, raise issue, clear.

6. Auto-approval countdown
   - For high-priority sources.
   - Seven-day window from notification date.

7. Trend modal
   - Opens when a metric trend button is clicked.
   - Shows metric KPI cards and weekly trend chart.

### Metric Grid Data Flow

1. User opens metric page or drills from source page.
2. The selected source is read from local source filter or the clicked source bridge.
3. SQL loads metric rows for selected market, brand, source, timeframe, comparison period, and optional customer/pack/territory.
4. Current and reference scores are calculated.
5. Completion and compliance deltas are calculated.
6. Failed checks count is calculated.
7. Existing approvals/issues are merged from `dq_dashboard.metric_level_summary`.
8. Rows are sorted by failed checks and completion score.

### Metric Grid Completion

For each metric:

```text
Completion score = AVG(completion_flag current) * 100
Completion score reference = AVG(completion_flag reference) * 100
Completion change = Completion score - Completion score reference
```

### Metric Grid Compliance

For each metric:

```text
Compliance score =
  AVG(
    Check1_2 pass,
    Check2 pass,
    population_check_flag,
    cpm_flag,
    launch_delist_score,
    operational_dual_score
  )
```

Reference compliance:

```text
Compliance score reference =
  same formula using reference-period check scores
```

Change:

```text
Compliance change = Compliance score - Compliance score reference
```

### Metric KPI Cards

The metric page KPI cards are source-level rollups for the current filter context, not just one row.

Base cards:

- Overall completion
- Data type compliance
- Outlier compliance

Additional cards for `MDL` and `eMMM`:

- Population compliance
- CPM compliance
- Operational dual presence

Additional card for `MPM`, `Nielsen`, `Nielsen IQ`, `Nielsen MPM`, and `Global NSR`:

- Launch/de-list compliance

Each card shows:

```text
current value
delta = current value - reference value
```

### Failed Checks Count

Business meaning:

The number of applicable validation checks that are not fully passing for a metric row.

Failed check conversion:

```text
blank/null -> not counted
numeric < 100 -> failed
numeric >= 100 -> passed
Passed or Present -> passed
Failed, Delist, Launched -> failed
```

Normal source failed-check columns:

```text
Completion score
Check1_2 pass
Check2 pass
population_check_flag
cpm_flag
launch_delist_flag
cust_mean
Check3 pass
inf_dual_presence
operational_dual_presence
```

MDL failed-check columns exclude completion:

```text
Check1_2 pass
Check2 pass
population_check_flag
cpm_flag
launch_delist_flag
cust_mean
Check3 pass
inf_dual_presence
operational_dual_presence
```

Validation status:

```text
failed_checks_count = 0 -> No validation required
failed_checks_count > 0 -> Validation required
```

For high-priority sources, users can approve or raise an issue.

### Approval Workflow

High-priority sources include:

```text
MDL
CCI
CCEP
Nielsen MPM
MPM
Nielsen IQ
Nielsen
Bottler
```

Workflow:

1. Reviewer selects one or more metric rows.
2. Reviewer chooses approve or raise issue.
3. Dashboard records the action in `dq_dashboard.metric_level_summary`.
4. The row status reflects the latest action.
5. Auto-approval can apply after the configured seven-day window.

### Trend Modal

Purpose:

The trend modal gives evidence for why a metric failed or changed. It is the detailed chart view behind a metric row or a matched portfolio tile.

Modal title:

```text
<Metric name> | Source: <Source>
```

When opened from portfolio detail, the modal should also display available granular context:

```text
Brand: <Brand>
Customer: <Customer>
Pack group: <Pack group>
Territory: <Territory>
```

Modal controls:

- Brand
- Timeframe
- Compare with

Modal KPI cards:

- General/data type compliance
- Outlier compliance
- Correlation or operational/launch-de-list related status depending on source
- CPM or population context for media metrics where applicable

Chart:

- Weekly metric trend.
- Outlier upper bound.
- Outlier lower bound.
- Reference period marker.
- Current period marker.
- Optional CPM line.
- Optional population line.
- Optional dual metric line.

Missing value message:

If a paired metric is not present, the modal can show a message such as:

```text
Values are not present for <paired metric>.
```

### Metric AI Context

Artemis AI should answer metric-level questions using:

- current filters,
- selected source,
- selected brand,
- selected customer/pack/territory if present,
- KPI cards,
- metric rows,
- failed checks count,
- completion and compliance scores,
- check-level scores,
- approval status,
- trend modal context if open.

Good AI response pattern:

```text
For <Source> in <Timeframe>, <Metric> has completion <x>% and compliance <y>%.
It has <n> failed checks: <list failed checks>.
The largest issue is <check name> because its score/status is <value>.
Compared with <reference>, completion changed by <delta1> and compliance changed by <delta2>.
Next step: review the trend modal and then approve or raise issue based on the evidence.
```

## 8. End-To-End User Journey

### Journey 1: Find The Weakest Portfolio Cell

1. User opens Portfolio View.
2. User selects country, timeframe, source, KPI.
3. User scans heatmap for red cells.
4. User clicks a weak brand/metric tile.
5. User reviews lower metric detail.
6. User clicks the granular red/green detail box.
7. If matching trend data exists, modal opens.
8. User reviews chart and check cards.
9. User goes to Metric Level Summary if validation action is needed.

AI should explain:

- selected filters,
- weakest cell,
- why it is weak,
- whether issue is broad brand-level or localized to customer/pack/original metric,
- next action.

### Journey 2: From Overall Health To Source Root Cause

1. User opens Overall Summary.
2. User checks completion, compliance, stability.
3. If completion/compliance is low, user navigates to Source Level Summary.
4. User identifies the weak source card.
5. User clicks the source to open Metric Level Summary.

AI should explain:

- overall completion/compliance/stability,
- largest negative movement,
- which source to inspect next.

### Journey 3: Investigate Source-Level Weakness

1. User opens Source Level Summary.
2. User sorts/scans source cards mentally by low completion/compliance.
3. User clicks source card.
4. Metric Level Summary opens with source selected.
5. User sorts by failed checks.

AI should explain:

- source ranking,
- low source,
- metrics impacted,
- recommended drillthrough.

### Journey 4: Validate A Metric

1. User opens Metric Level Summary.
2. User filters source/timeframe/customer/pack if needed.
3. User checks KPI cards for broad source quality.
4. User reviews grid rows with failed checks.
5. User clicks Trend.
6. User reviews trend/outlier/reference/current evidence.
7. User approves if acceptable or raises issue if quality failure is real.

AI should explain:

- exact failed checks,
- score movement,
- trend evidence,
- approval or issue recommendation.

## 9. Suggested User Stories

### Portfolio View Story

As a data quality reviewer, I want to see completion and compliance by brand and metric across the full portfolio so that I can quickly identify weak brand/metric cells and drill into the customer, pack, territory, or original media metric causing the issue.

Acceptance context:

- User can switch media/non-media view.
- User can select timeframe, source, and KPI.
- Red cells indicate values below 100.
- Green cells indicate full 100.
- Clicking a cell selects the brand/metric.
- Clicking a valid granular detail tile opens the same trend modal used by metric-level summary.
- No modal opens when matching trend data is not available.

### Overall Summary Story

As a data quality reviewer, I want high-level completion, compliance, and stability scores for the selected market and brand so that I can decide whether to investigate missing data, failed checks, or restated historical instability.

Acceptance context:

- Completion and compliance show current score and change vs reference.
- Stability donut opens a modal.
- Stability modal lists unstable metrics and brands.
- Stability chart compares previous dataset version and latest restated data.

### Source Level Story

As a data quality reviewer, I want to see completion and compliance by source so that I can identify which upstream data source is driving quality problems and drill into the metric-level page for that source.

Acceptance context:

- Each source card shows metric count, completion, compliance, and deltas.
- High-priority sources are prominent.
- Clicking a card opens metric-level summary for that source.
- Source downloads and notifications are available where configured.

### Metric Level Story

As a data quality reviewer, I want to see metric-level failed checks and trend evidence so that I can approve clean metrics, raise issues for failed metrics, and provide evidence to source owners.

Acceptance context:

- Grid rows show completion, compliance, failed check count, and check-level results.
- Trend button opens the detailed trend modal.
- Failed checks count excludes blank/not-applicable checks.
- Approval and raise-issue actions persist to the DQ summary table.
- Auto-approval applies after the configured review window for high-priority sources.

## 10. Prompt Context For Training Artemis AI

Use this structure when giving page context to Artemis AI:

```text
You are Artemis AI, an assistant for the Artemis Data Integrity Hub monthly refresh dashboard.
Always ground your answer in the current page, filters, selected source, selected brand, selected metric, and visible KPI values.
Do not invent values. If a value is absent, say it is not available or not applicable.

Definitions:
- Completion = average completion_flag * 100.
- Compliance = average of applicable check scores only.
- Data type compliance = average data_type_check_result * 100.
- Outlier compliance = average outlier_check * 100.
- Population compliance = average population_check_flag * 100, blank for spend metrics.
- CPM compliance = average cpm_flag * 100.
- Operational dual presence = failed only when reference fully passed and current fully failed; Passed = 100, Failed = 0.
- Launch/de-list = Present, Delist, or Launched based on current vs reference presence; score is Present count divided by valid statuses.
- Stability = stable instances divided by total instances, comparing latest restated data to previous dataset version.

Response style:
1. State the selected context.
2. State the most important finding.
3. Quote the exact score(s) and deltas.
4. Explain which check or dimension is driving the issue.
5. Recommend the next dashboard action.
```

Example response:

```text
For Country 2 in January 2026, the Portfolio View is showing Completion for MDL in media view.
The weakest visible brand cell is Brand 7 at 10%, while Brand 2 is also below target at 54%.
Because the selected detail tiles are media metrics under Brand 1, the next step is to click the lower metric detail tile and inspect the trend modal for the original media metric.
If the modal does not open, the selected tile does not have a matching trend context for the current filters.
```

## 11. AI Guardrails

Artemis AI should:

- Use exact current page numbers from the page context stores when available.
- Mention selected filters before interpreting scores.
- Treat null/blank checks as not applicable, not as failures.
- Use "percentage points" for score deltas.
- Avoid saying a source is bad unless it has low scores or negative deltas in the visible data.
- Explain whether an issue is completion-driven, compliance-driven, stability-driven, or launch/de-list-driven.
- Recommend dashboard actions, not unsupported operational decisions.
- Never open or promise a modal unless the selected row/tile has matching trend data.

Artemis AI should not:

- Average visible rounded percentages manually if an official current score is available.
- Count null checks as failed.
- Treat `Launched` or `Delist` as generic outlier failures.
- Mix media-view original metrics with non-media customer/pack details.
- Compare a current month to an unspecified reference period.