Chapter 3: User Stories & Personas

3.1 Overview

This chapter defines the people who will use AdPriority, what they need from it, and how every requirement traces back to a real problem experienced by a real user type. The user stories documented here serve as the contract between design and implementation: every feature built must satisfy at least one story, and every story must have acceptance criteria that can be verified in a demo or automated test.

Story Format

All stories follow the standard format:

As a [role],
I want to [capability],
So that [benefit].

Each story includes:

• Acceptance criteria – specific, testable conditions that must be true for the story to be considered complete
• Priority – using the MoSCoW framework mapped to P0-P3
• Effort – estimated implementation complexity (Low, Medium, High)
• Phase – which development phase delivers this story
• Dependencies – other stories or infrastructure that must exist first

Priority Definitions

Story ID Conventions

3.2 User Personas

Each persona represents a distinct user type with different goals, constraints, and technical comfort levels. These are not hypothetical archetypes; they are composites of real Shopify merchants drawn from market research and, in one case, the actual store that will validate the MVP.

3.2.1 Persona: Small Store Owner (“Sarah”)

PERSONA PROFILE: SARAH
=======================

  Role:           Store owner and sole operator
  Store size:     200 - 1,000 products
  Monthly revenue: $15,000 - $80,000
  Google Ads spend: $500 - $3,000/month
  Team size:      1 (herself)
  Tech comfort:   Moderate -- comfortable with Shopify admin, intimidated by feed tools
  AdPriority tier: Starter ($29/mo)

Background: Sarah runs a women’s fashion boutique on Shopify. She launched Google Ads six months ago and is spending $1,500/month on a Performance Max campaign. She knows the ads are working – she can see the sales attribution in Shopify – but she suspects she is wasting money advertising products that are out of season or overstocked. She tried DataFeedWatch during a free trial but abandoned it after 30 minutes because the interface was overwhelming.

Pain Points:

Goals:

1. Automate ad spend allocation so she can focus on buying and customer service
2. Stop advertising out-of-season products without manual intervention
3. Give new arrivals a promotional boost automatically
4. Improve ROAS enough to justify increasing her Google Ads budget

How Sarah Uses AdPriority:

• Installs the app and connects her Google account in under 5 minutes
• Reviews the auto-suggested category mappings and makes minor adjustments
• Sets up the seasonal calendar (defaults work for her climate zone)
• Checks the dashboard weekly to see priority distribution
• Occasionally overrides a priority for a product she wants to promote or suppress

Key Stories: US-01, US-02, US-05, US-06, US-30, US-31, US-34

3.2.2 Persona: Growing Brand Manager (“Marcus”)

PERSONA PROFILE: MARCUS
========================

  Role:           E-commerce manager at a growing streetwear brand
  Store size:     1,000 - 10,000 products
  Monthly revenue: $100,000 - $500,000
  Google Ads spend: $5,000 - $20,000/month
  Team size:      3-5 (marketing, warehouse, customer service)
  Tech comfort:   High -- uses Shopify APIs, comfortable with spreadsheets and automation
  AdPriority tier: Growth ($79/mo)

Background: Marcus manages the online store for a mid-sized streetwear brand with 4,200 active products. He runs three PMAX campaigns segmented by product category, but his custom labels are six months out of date because updating them requires exporting a CSV from their product database, manually adding label columns, and uploading it to Google Merchant Center. The process takes him a full day each time he does it, so it only happens when performance drops noticeably.

Pain Points:

Goals:

1. Systematic, repeatable approach to product prioritization that the whole team can follow
2. Seasonal automation that eliminates the quarterly manual update grind
3. Confidence that new arrivals are automatically promoted on day one
4. Ability to bulk-edit priorities when running promotions or clearance events
5. Preview mode so he can verify changes before they sync to GMC

How Marcus Uses AdPriority:

• Spends 30 minutes on initial setup: category mappings, seasonal calendar, tag rules
• Relies on seasonal automation to handle the quarterly transitions
• Uses bulk edit for clearance events and promotional pushes
• Checks the preview before each sync to catch mistakes
• Delegates day-to-day monitoring to a junior team member via the dashboard

Key Stories: US-01, US-02, US-03, US-04, US-06, US-07, US-08, US-32, US-36

3.2.3 Persona: Agency Account Manager (“Diana”)

PERSONA PROFILE: DIANA
=======================

  Role:           Senior account manager at a digital marketing agency
  Stores managed: 12 Shopify stores across 8 clients
  Combined catalog: 30,000+ products
  Combined ad spend: $80,000+/month
  Team size:      4 (herself + 3 account executives)
  Tech comfort:   Expert -- uses APIs, scripts, and automation daily
  AdPriority tier: Pro/Enterprise ($199+/mo)

Background: Diana manages Google Ads for 8 retail clients, all on Shopify. Each client has unique product categories, seasonal patterns, and brand priorities. She currently maintains a master spreadsheet that tracks which custom labels each client should have, but the spreadsheet is always behind reality. Her account executives spend 6-8 hours per client per quarter updating labels manually. She has pitched the idea of a centralized tool to her director, who approved a $200-300/month budget for any tool that can cut this work in half.

Pain Points:

Goals:

1. Manage all client stores from a single dashboard
2. Clone proven rule sets from one store to another to accelerate onboarding
3. Generate per-client usage and performance reports for billing justification
4. Demonstrate measurable ROAS improvement to retain and upsell clients
5. Reduce per-client management time from 6-8 hours to under 1 hour per quarter

How Diana Uses AdPriority:

• Sets up each client store once with category mappings and seasonal rules
• Clones her “fashion retail” rule template to new fashion clients
• Checks the multi-store dashboard daily for sync failures or alerts
• Generates monthly per-store performance reports for client meetings
• Uses ROAS tracking to demonstrate the value of the service

Key Stories: US-20, US-21, US-22, US-37, US-10, US-12

3.2.4 Persona: Nexus Clothing Owner (“Will”) – Validation User

PERSONA PROFILE: WILL
======================

  Role:           Owner and operator of Nexus Clothing
  Store:          nexus-clothes.myshopify.com
  Store size:     5,582 products (2,425 active), 90 product types, 175 vendors
  GMC catalog:    124,060 variants
  Google Ads spend: Active PMAX campaigns
  Team size:      1 for digital operations
  Tech comfort:   High -- runs Docker infrastructure, builds custom tools
  AdPriority tier: Phase 0 (MVP validation)

Background: Will is the developer building AdPriority and the owner of the first store that will use it. Nexus Clothing is a multi-location streetwear retailer with a complex product catalog spanning t-shirts, jeans, outerwear, headwear, footwear, and accessories. The store runs Google Ads Performance Max campaigns but has only 7 out of 124,060 GMC variants with any custom label set (0.006% coverage). This means Google’s AI is treating every product equally, regardless of season, margin, or demand.

Pain Points:

Goals:

1. Validate the AdPriority concept with real data before investing in SaaS development
2. Score all 2,425 active products with appropriate priorities
3. Deploy a supplemental feed covering all ~15,000-20,000 active variants
4. Restructure PMAX campaigns around priority-based asset groups
5. Measure a 15%+ ROAS improvement within 30 days
6. Document the entire process for replication in the SaaS product

How Will Uses AdPriority:

• Phase 0 is a semi-automated process: category mapping spreadsheet, Python scripts, Google Sheets API
• Validates the 20 category groups against real product data
• Tests the seasonal matrix with winter priorities first
• Monitors ROAS daily during the 30-day measurement window
• Documents every decision and outcome for the blueprint book

Key Stories: US-01, US-02, US-05, US-03, US-31, US-33, US-34

Why This Persona Matters: Will is not a future hypothetical user. He is the first user, and his store provides the real-world complexity (5,582 products, 90 types, 124K GMC variants) that validates whether AdPriority’s approach works at scale. Every design decision in Phase 0 is tested against Nexus Clothing data.

3.3 Epic: Product Priority Management

This epic covers the core functionality that makes AdPriority useful: assigning, managing, and automating priority scores on products.

Story US-01: Assign Priority Scores

As a store owner, I want to assign priority scores (0-5) to my products, So that I can control how much ad budget is allocated to each product.

Acceptance Criteria:

• User can view a paginated product list showing product name, image thumbnail, product type, current priority score, and sync status
• Each priority score displays with a color-coded badge (0=gray, 1=red, 2=orange, 3=yellow, 4=blue, 5=green)
• User can click on a product row to open a detail panel showing all product attributes and priority history
• User can change a product’s priority score via a dropdown or slider in the detail panel
• Priority change is saved to the database immediately on selection (no separate save button)
• Saving a priority change creates an audit trail entry recording the old score, new score, user, timestamp, and source (“manual”)
• Saving a priority change adds a GMC sync queue entry for the next sync cycle
• A toast notification confirms the priority change was saved
• If the save fails, the UI reverts to the previous score and shows an error message
• Score labels are visible alongside the numeric value (“5 - Push Hard”, “0 - Exclude”)

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: Product import from Shopify (database must have products to score)

Nexus Validation: In Phase 0, this is done via the category mapping spreadsheet and Python scripts. The SaaS version replaces that manual process with the UI described above.

Story US-02: Category-Based Rules

As a store owner, I want to set category-based rules so new products automatically inherit priority scores, So that I do not have to manually score every new product that arrives in my catalog.

Acceptance Criteria:

• User can view a list of all Shopify product types found in their catalog, grouped by AdPriority category groups
• User can assign a default priority score (0-5) to each category group
• When a new product is created in Shopify (via webhook), the system looks up its product type, matches it to a category group, and assigns the default priority
• When a product’s product type changes in Shopify (via webhook), the system re-evaluates its category-based priority
• Category rules are lower priority than manual overrides (a manually-set score is not overwritten by a category rule)
• User can create custom category groups by combining multiple Shopify product types
• User can edit the name and default priority of any category group
• User can see how many products are in each category group
• A “Preview” button shows which products would be affected by a rule change before it is applied
• Changes to category rules trigger a bulk recalculation of affected product priorities

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-01 (priority scoring must exist), product import (product types must be available)

Nexus Validation: The 20 category groups designed during research (t-shirts, jeans-pants, outerwear-heavy, headwear-caps, etc.) were derived from grouping Nexus Clothing’s 90 product types. Phase 0 validates these groupings against real inventory.

Story US-06: Manual Override

As a store owner, I want to manually override any automatic priority assignment, So that I maintain final control over which products are advertised and at what level.

Acceptance Criteria:

• User can set a priority score on any individual product that overrides all automatic rules (category, seasonal, new arrival)
• A manual override is visually indicated on the product list (e.g., a lock icon or “Override” badge next to the score)
• The override persists across seasonal transitions and rule recalculations
• User can remove the override to return the product to automatic rule-based scoring
• Removing an override immediately recalculates the product’s priority based on current active rules
• The audit trail records override creation and removal as distinct events
• Override reason is optionally recordable (free text field, e.g., “CEO wants this promoted for store event”)
• Bulk override is supported: user can select multiple products and apply a manual override to all of them
• A filter option allows viewing only products with active overrides
• Override count is displayed on the dashboard summary

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: US-01 (priority scoring), US-02 (category rules must exist for override to be meaningful)

Design Note: The override hierarchy is fundamental to the scoring engine. The precedence order is: (1) manual override, (2) exclusion tags, (3) inventory warnings, (4) new arrival boost, (5) tag modifiers, (6) seasonal calendar, (7) category default. Manual override sits at the top because the store owner must always have the final word.

Story US-07: Bulk Edit Priorities

As a store owner, I want to bulk-edit priorities for multiple products at once, So that I can efficiently manage large catalog changes like clearance events or seasonal promotions.

Acceptance Criteria:

• User can select multiple products via checkboxes in the product list
• A “Select All” option selects all products on the current page; a “Select All Matching” option selects all products matching the current filter (even across pages)
• With products selected, a bulk action toolbar appears showing the count of selected products
• Bulk action: “Set Priority” – assigns a chosen score (0-5) to all selected products as manual overrides
• Bulk action: “Remove Override” – removes manual overrides from all selected products, returning them to rule-based scoring
• Bulk action: “Apply Rule” – recalculates priorities for selected products based on current rules
• A confirmation dialog shows the number of products affected and the action to be taken before execution
• Bulk operations process at 1,000+ products per minute
• Progress indicator displays during bulk operations that take longer than 2 seconds
• Bulk operations create individual audit trail entries for each affected product
• Bulk operations add affected products to the GMC sync queue

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-06 (manual override)

Example Use Cases:

3.4 Epic: Seasonal Automation

This epic covers the features that differentiate AdPriority from manual label management: automatic priority adjustments based on a configurable seasonal calendar.

Story US-03: Seasonal Priority Adjustment

As a store owner, I want seasonal automation so my priorities adjust automatically throughout the year, So that I do not have to remember to update labels four times per year and my ad spend always matches the current season.

Acceptance Criteria:

• User can define season boundaries (default: Winter Dec 1 - Feb 28, Spring Mar 1 - May 31, Summer Jun 1 - Aug 31, Fall Sep 1 - Nov 30)
• User can customize season start and end dates to match their business cycle
• User can configure a Category x Season priority matrix defining the base score for each category in each season
• The matrix displays as an editable table with categories as rows and seasons as columns
• When the current date crosses a season boundary, the system automatically recalculates priorities for all products affected by seasonal rules
• Seasonal recalculation respects the override hierarchy (manual overrides are not changed)
• User can manually trigger a season change early or late (e.g., “Switch to Summer now” if the weather turns early)
• A preview panel shows what will change at the next season boundary, including product counts per category and the old vs. new scores
• Seasonal transitions are logged in the audit trail with the trigger source (“automatic” or “manual”)
• A notification is sent to the user when a seasonal transition completes, summarizing the number of products affected

Priority: P1 (Should Have) Effort: High Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules provide the category groups)

Seasonal Matrix Example (from Nexus Clothing research):

CATEGORY x SEASON PRIORITY MATRIX
===================================

                          Winter   Spring   Summer   Fall
                          ------   ------   ------   ----
  T-Shirts                  2        4        5       3
  Shorts                    0        3        5       1
  Jeans & Pants             4        3        3       4
  Hoodies & Sweatshirts     5        3        1       5
  Outerwear - Heavy         5        1        0       4
  Outerwear - Light         3        4        3       4
  Headwear - Caps           3        3        3       3
  Headwear - Cold Weather   5        1        0       4
  Footwear - Sneakers       3        3        4       3
  Footwear - Sandals        0        3        5       1
  Underwear & Basics        2        2        2       2
  Accessories               3        3        3       3
  Jerseys & Sports          2        3        4       3
  Sets & Matching           3        3        4       3
  Suits & Formal            3        3        3       3
  Swimwear                  0        3        5       0
  Bags & Luggage            3        3        3       3
  Jewelry                   3        3        3       3
  Sleepwear                 3        2        2       3
  Kids                      3        3        3       3

Design Note: The matrix is the heart of seasonal automation. A store owner fills this in once (or accepts the defaults for their industry), and the system handles every transition automatically. This single feature eliminates the most common reason merchants let their custom labels go stale.

Story US-04: New Arrival Boost

As a store owner, I want new arrivals to automatically get high priority for a configurable period, So that new products get immediate advertising exposure during their critical launch window.

Acceptance Criteria:

• User can enable or disable the new arrival boost feature
• User can configure the boost duration (default: 14 days, range: 1-90 days)
• User can configure the boost priority score (default: 5, range: 1-5)
• When a new product is created in Shopify (detected via webhook or import), the system assigns the configured boost priority
• The boost is applied only if the resulting score is higher than the score from other rules (boost does not reduce a score)
• User can enable gradual decay: the priority decreases by 1 level at configurable intervals during the boost period
• Example decay: Day 1-5 = priority 5, Day 6-10 = priority 4, Day 11-14 = priority 3, then reverts to rule-based score
• Products with active boosts are visually indicated in the product list (e.g., “New Arrival” badge with countdown)
• User can manually end a boost early on any individual product
• Manual overrides take precedence over new arrival boosts
• When the boost expires, the product’s priority reverts to its rule-calculated score (seasonal + category)
• Boost expiration triggers a recalculation and GMC sync queue entry

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), Shopify webhook for products/create

Gradual Decay Configuration Example:

NEW ARRIVAL BOOST: GRADUAL DECAY
=================================

  Boost Duration: 14 days
  Starting Score: 5 (Push Hard)
  Decay Interval: Every 5 days

  Timeline:
  Day  1 -----> Day  5:  Priority 5  (Push Hard)
  Day  6 -----> Day 10:  Priority 4  (Strong)
  Day 11 -----> Day 14:  Priority 3  (Normal)
  Day 15 onwards:        Reverts to rule-based score

  Product Example: "New Jordan Craig Stacked Jeans"
  - Created: Feb 1
  - Category default: 4 (Jeans & Pants, Winter)
  - Boost: Feb 1-5 = 5, Feb 6-10 = 4, Feb 11-14 = 3*
  - Feb 15 onwards: 4 (category rule takes over)

  * Note: Day 11-14 the decay score (3) is LOWER than the
    category score (4), so category score wins. Boost only
    elevates, never reduces.

3.5 Epic: GMC Synchronization

This epic covers the connection between AdPriority and Google Merchant Center – the mechanism that makes priority scores actionable in Google Ads campaigns.

Story US-05: Sync Status Visibility

As a store owner, I want to see which products are synced to GMC and their current custom labels, So that I can verify my priority settings are actually reaching Google Ads.

Acceptance Criteria:

• The product list includes a “Sync Status” column showing one of: Synced, Pending, Error, Not in GMC
• “Synced” means the product’s current priority score matches what was last written to the supplemental feed
• “Pending” means the priority score has changed since the last sync and is queued for the next sync cycle
• “Error” means the last sync attempt for this product failed (with a tooltip showing the error message)
• “Not in GMC” means the product could not be matched to a GMC product ID
• A sync summary panel on the dashboard shows: total synced, total pending, total errors, last sync timestamp, next scheduled sync
• User can click “Sync Now” to trigger an immediate sync cycle for all pending products
• User can click on an individual product to see its sync history (last 10 sync events with timestamps and statuses)
• Filtering the product list by sync status is supported (e.g., show only “Error” products)
• A warning banner appears if more than 5% of products are in Error status
• The dashboard shows the custom label values currently written to GMC for each synced product

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-01 (products must have scores to sync), Google Sheets API integration, GMC supplemental feed connection

Sync Status Flow:

SYNC STATUS LIFECYCLE
======================

  Product priority changed (manual, rule, or seasonal)
       |
       v
  Status: PENDING
  (queued for next sync cycle)
       |
       |  Sync cycle runs (scheduled or manual)
       v
  Write to Google Sheet
       |
       +---> Success --> Status: SYNCED
       |                 (timestamp updated)
       |
       +---> Failure --> Status: ERROR
                         (error message recorded, retry queued)

Story US-08: Preview Before Sync

As a store owner, I want to preview priority changes before they sync to GMC, So that I can verify changes are correct and avoid pushing wrong labels to my live ads.

Acceptance Criteria:

• Before any sync cycle executes, a preview screen shows all products with pending changes
• The preview displays: product name, current GMC label value, proposed new label value, and the reason for the change (manual, rule, seasonal)
• User can approve the sync to proceed or cancel to hold the changes
• User can remove individual products from the pending sync while keeping others
• For automatic syncs (scheduled), the preview is recorded in a sync log that the user can review after the fact
• For rule changes and seasonal transitions that affect many products, a summary view shows affected product counts per category and per score change direction (increases vs. decreases)
• A diff view highlights products whose score is changing by more than 2 levels (potential large impact)
• The preview includes a “Download CSV” option to export the pending changes for offline review
• Preview data refreshes in real-time as the user makes changes on other pages

Priority: P2 (Nice to Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-05 (sync pipeline must exist for preview to be meaningful)

Why This Matters: Marcus (the growing brand manager persona) has pushed wrong labels to GMC twice due to errors in CSV exports. A preview step prevents this class of error entirely. For Sarah (small store owner), the preview provides reassurance that the system is doing the right thing.

3.6 Epic: Performance Analytics

This epic covers the analytics features available in the Pro tier that connect priority scoring to actual advertising performance. These features require Google Ads API integration.

Story US-10: Priority Tier Metrics

As a marketing manager, I want to see performance metrics by priority tier, So that I can understand whether my priority scoring strategy is actually improving ad performance.

Acceptance Criteria:

• A performance dashboard displays key metrics broken down by priority tier (0-5)
• Metrics shown per tier: impressions, clicks, cost, conversions, revenue, ROAS, CPC, conversion rate
• Data is pulled from Google Ads API and aggregated by the priority score assigned in AdPriority
• Metrics are available for configurable date ranges (last 7 days, 30 days, 90 days, custom)
• A bar chart shows spend distribution across priority tiers
• A table shows the top 10 performing products within each priority tier
• Data refreshes at least once daily (with timestamp of last refresh)
• A summary card highlights the ROAS for priority 5 products vs. the overall catalog ROAS
• Export to CSV is available for all metrics tables
• If Google Ads is not connected, the dashboard shows a clear prompt to connect with an explanation of what metrics will become available

Priority: P2 (Nice to Have) Effort: High Phase: Phase 2-3 Dependencies: Google Ads API integration, US-01 (products must have scores to aggregate against)

Example Dashboard Output:

PERFORMANCE BY PRIORITY TIER (Last 30 Days)
=============================================

  Tier  | Products | Impressions |  Clicks  |   Cost   | Revenue  |  ROAS
  ------+----------+-------------+----------+----------+----------+-------
    5   |      312 |    142,000  |   4,260  |  $8,520  | $34,080  |  4.0x
    4   |      589 |     98,000  |   2,450  |  $3,675  | $12,862  |  3.5x
    3   |      724 |     56,000  |   1,120  |  $1,344  |  $3,628  |  2.7x
    2   |      398 |     12,000  |     240  |    $192  |    $384  |  2.0x
    1   |      201 |      3,000  |      45  |     $27  |     $40  |  1.5x
    0   |      201 |          0  |       0  |      $0  |      $0  |   --
  ------+----------+-------------+----------+----------+----------+-------
  Total |    2,425 |    311,000  |   8,115  | $13,758  | $50,994  |  3.7x

  Insight: Priority 5 products generate 67% of revenue with 62% of spend.
           Priority 0-1 products correctly excluded from budget waste.

Story US-11: ROAS-Based Recommendations

As a marketing manager, I want recommendations for priority adjustments based on ROAS data, So that I can continuously optimize my scoring strategy with data-driven decisions instead of guesswork.

Acceptance Criteria:

• The system analyzes Google Ads performance data and identifies products whose priority score does not match their actual performance
• Recommendations fall into three categories: “Increase Priority” (high ROAS, low priority), “Decrease Priority” (low ROAS, high priority), “Review” (anomalous patterns)
• Each recommendation shows: product name, current priority, suggested priority, reason, supporting metrics (ROAS, spend, revenue)
• Recommendations require a minimum data threshold (e.g., 100+ impressions, 14+ days of data) to avoid noise
• User can accept a recommendation with one click, which applies the suggested priority as a manual override
• User can dismiss a recommendation, which hides it for 30 days
• A recommendation quality score tracks how often accepted recommendations lead to improved ROAS
• Recommendations are refreshed weekly (not real-time, to allow for statistical significance)
• A notification badge shows the count of new recommendations since last review

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-10 (performance metrics must exist first), sufficient data history (minimum 30 days)

Example Recommendations:

Story US-12: Before/After Comparison

As a marketing manager, I want to compare performance before and after priority changes, So that I can measure the impact of my optimization decisions and report results to stakeholders.

Acceptance Criteria:

• When a priority change is deployed, the system records a “change event” with the date and affected products
• A comparison report shows key metrics for a configurable period before the change vs. after the change
• Metrics compared: ROAS, total spend, total revenue, CPC, conversion rate, impressions
• The comparison isolates the products that were affected by the change (not the entire catalog)
• A chart overlays before and after trendlines for visual comparison
• Statistical confidence indicator shows whether the improvement is statistically significant or within normal variance
• Comparison reports can be exported as PDF for sharing with stakeholders
• Historical comparisons are stored and accessible from a “Change History” view
• The system auto-generates a comparison report 30 days after any major change event (10+ products affected)

Priority: P2 (Nice to Have) Effort: High Phase: Phase 2-3 Dependencies: US-10 (performance metrics), US-01 (change events recorded in audit trail)

3.7 Epic: Multi-Store Management

This epic covers the Enterprise tier features that allow agencies and multi-brand operators to manage multiple Shopify stores from a single AdPriority account.

Story US-20: Multi-Store Dashboard

As an agency user, I want to manage multiple stores from one dashboard, So that I can efficiently oversee all my clients’ priority scoring without logging in and out of separate accounts.

Acceptance Criteria:

• User can link multiple Shopify stores to a single AdPriority account
• A store switcher in the navigation allows instant switching between stores
• An aggregate dashboard shows key metrics across all stores: total products scored, total pending syncs, total errors, total stores active
• Each store card on the aggregate dashboard shows: store name, product count, last sync status, overall ROAS (if Google Ads connected)
• Clicking a store card navigates to that store’s individual dashboard (identical to single-store experience)
• User can assign team members to specific stores with role-based access (viewer, editor, admin)
• Store-specific settings (seasons, rules, overrides) are independent between stores
• Adding a new store follows the same OAuth flow as initial setup
• Removing a store requires confirmation and offers a data export option before deletion
• The aggregate dashboard highlights stores with issues (sync errors, stale rules, no recent activity)

Priority: P3 (Future) Effort: Very High Phase: Phase 3+ Dependencies: Complete single-store feature set (US-01 through US-08), multi-tenant database architecture

Story US-21: Rule Cloning Between Stores

As an agency user, I want to clone rules between stores, So that I can quickly onboard new clients by reusing proven configurations from similar stores.

Acceptance Criteria:

• User can select a source store and export its rule configuration as a “rule template”
• Rule templates include: category group definitions, category-to-priority mappings, seasonal matrix, tag modifier rules, new arrival boost settings
• Rule templates do NOT include: product-specific overrides, sync settings, Google account credentials
• User can apply a rule template to a destination store
• When applying a template, the system shows a preview of what will change in the destination store
• The system identifies unmappable categories (product types in the destination store that do not exist in the template) and prompts the user to map them manually
• User can save named templates for reuse (e.g., “Fashion Retail - US” or “Sporting Goods - Seasonal”)
• Templates are versioned; updating a template does not retroactively change stores that previously applied it
• A template library shows all saved templates with descriptions, creation dates, and the number of stores using each

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-20 (multi-store management), US-02 (category rules), US-03 (seasonal rules)

Story US-22: Per-Store Usage Reports

As an agency user, I want per-store usage reports for billing, So that I can accurately bill clients for the management services I provide using AdPriority.

Acceptance Criteria:

• A reporting page shows per-store usage metrics for a configurable date range
• Metrics include: number of priority changes made, number of sync cycles completed, number of products managed, rule changes applied, overrides set
• Reports can be filtered by date range (monthly is the default for billing cycles)
• Reports can be exported as CSV or PDF
• Each report includes the store name, AdPriority plan tier, and billing period
• An optional notes field allows the agency to add client-facing context to each report
• Automated monthly report generation can be scheduled with email delivery
• Reports include a visual summary chart suitable for inclusion in client presentations

Priority: P3 (Future) Effort: Medium Phase: Phase 3+ Dependencies: US-20 (multi-store management), audit trail data

3.8 Discovered Stories

During research, requirements analysis, and persona development, the following stories emerged as necessary for a complete product experience. These stories fill gaps between the explicit requirements and the actual user workflows.

Story US-30: Google Account Connection

As a store owner, I want to connect my Google account so that my custom labels sync automatically, So that I do not have to manually export and upload data to Google Merchant Center.

Acceptance Criteria:

• A settings page provides a “Connect Google Account” button that initiates Google OAuth 2.0
• OAuth requests only the scopes needed: Google Sheets API (for supplemental feed), and optionally Google Ads API (for Pro tier)
• After successful authentication, the system displays the connected Google account email
• The system automatically creates a Google Sheet in the user’s Google Drive for the supplemental feed
• The Sheet is pre-formatted with the correct columns (id, custom_label_0 through custom_label_4)
• Setup instructions guide the user to add the Sheet URL as a supplemental feed in GMC
• A “Test Connection” button verifies the Sheet is accessible and writable
• User can disconnect the Google account at any time (with warning about sync implications)
• Token refresh is handled automatically; the user does not need to re-authenticate unless they revoke access
• If the token expires or is revoked, a prominent warning appears on the dashboard

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: None (this is a foundational integration)

Story US-31: Dashboard Overview

As a store owner, I want to see a dashboard overview so I can quickly understand my priority distribution, So that I know at a glance whether my catalog is well-optimized and if anything needs attention.

Acceptance Criteria:

• The dashboard is the default landing page when the app opens
• A priority distribution chart (bar or pie) shows the count of products at each priority level (0-5)
• A sync status summary shows: synced count, pending count, error count, last sync time
• An upcoming changes panel lists the next seasonal transition with date and affected product count
• Quick stats cards show: total products, products with overrides, new arrivals with active boost, products excluded (priority 0)
• A recent activity feed shows the last 10 priority changes with timestamps and sources
• If the user has not completed initial setup, the dashboard shows an onboarding checklist instead of metrics
• Dashboard data loads in under 2 seconds

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: US-01 (products must have scores to display)

Story US-32: CSV Import/Export

As a store owner, I want to import and export priorities via CSV, So that I can make bulk changes offline or integrate with other tools in my workflow.

Acceptance Criteria:

• An “Export” button downloads a CSV file with columns: product_id, product_title, product_type, current_priority, override_status, sync_status
• Export respects current filters (if the user has filtered the product list, only filtered products are exported)
• An “Import” button accepts a CSV file with at minimum: product_id and priority columns
• Import validates the file before applying: checks for valid product IDs, valid priority values (0-5), and correct column headers
• Import shows a preview of changes before applying, including: products found, products not found (invalid IDs), and score changes
• User confirms the import after reviewing the preview
• Import applies all changes as manual overrides
• Import creates audit trail entries for each changed product
• Import adds all changed products to the sync queue
• Error rows are reported in a downloadable error file with reasons

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-06 (manual override)

Story US-33: Sync Failure Alerts

As a store owner, I want to receive alerts when sync fails, So that I can take action before my ads run with stale or incorrect labels.

Acceptance Criteria:

• When a sync cycle fails (Google Sheets API error, authentication issue, or Sheet access revoked), the system sends an email notification to the store owner
• The email includes: error type, number of products affected, last successful sync timestamp, and a link to the app’s sync status page
• An in-app banner appears on the dashboard when the last sync attempt failed
• If sync has been failing for more than 24 hours, the banner escalates to a persistent warning
• User can configure notification preferences: email, in-app only, or both
• A webhook URL option allows integration with Slack or other notification tools (Pro tier)
• Alert frequency is rate-limited (maximum one email per hour for the same error type)
• When the sync recovers, a resolution notification is sent

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-05 (sync pipeline must exist)

Story US-34: Quick Setup (Under 5 Minutes)

As a store owner, I want to set up my store in under 5 minutes, So that I can start optimizing my ad spend immediately without a lengthy configuration process.

Acceptance Criteria:

• After app installation, a guided onboarding flow walks the user through setup in 4 steps or fewer
• Step 1: Connect Google account (OAuth popup, < 30 seconds)
• Step 2: Review auto-detected category groups (system groups product types automatically, user confirms or adjusts)
• Step 3: Choose a scoring template (e.g., “Fashion - Seasonal”, “General Retail”, “Custom”) which pre-fills the seasonal matrix and default priorities
• Step 4: Confirm and trigger first sync
• The entire flow is completable in under 5 minutes for a store with 500+ products
• Progress indicators show which steps are complete
• Users can skip steps and complete them later (dashboard shows incomplete setup items)
• A “Quick Start” video or walkthrough is available at each step
• If the user abandons setup mid-flow, they can resume where they left off
• Time to first sync is tracked as a product metric

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-30 (Google account connection), US-02 (category rules), product import

Story US-35: Unscored Product Detection

As a marketing manager, I want to see which products have no priority assigned, So that nothing falls through the cracks and every product has a deliberate priority decision.

Acceptance Criteria:

• A filter option shows products with no priority score (null or unassigned, distinct from priority 0 which is a deliberate exclusion)
• The dashboard shows a count of unscored products prominently if the count is greater than zero
• New products that arrive via webhook and do not match any category rule are flagged as “Unscored”
• An optional setting auto-assigns unscored products a default score (configurable, default: 3)
• A periodic check (daily) identifies any products that slipped through without scoring and flags them
• The unscored product list includes the product type, so the user can quickly create a category rule to cover the gap

Priority: P1 (Should Have) Effort: Low Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules)

Story US-36: Tag-Based Priority Rules

As a store owner, I want tag-based rules (e.g., “clearance” = priority 0) so that existing Shopify tags drive priorities, So that I can leverage the tagging I already do in Shopify without duplicating effort in AdPriority.

Acceptance Criteria:

• User can create rules that map Shopify product tags to priority modifiers or overrides
• Two rule types supported: “Set to” (absolute, e.g., tag “DEAD50” sets priority to 0) and “Adjust by” (relative, e.g., tag “NAME BRAND” adds +1)
• “Set to” rules function as overrides at the exclusion/tag level in the hierarchy
• “Adjust by” rules are additive modifiers that apply after category and seasonal scores
• User can set the priority order of tag rules (which tag rule wins if a product has multiple matching tags)
• Tag rules are applied automatically when products are imported or updated
• User can preview which products match a tag rule before activating it
• Common tag rules are suggested during onboarding based on detected tags in the catalog (e.g., if the system finds an “archived” tag on 3,000+ products, it suggests a rule to set those to priority 0)
• Tag rules respect the overall override hierarchy (manual overrides still win)

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules), product import (tags must be available)

Nexus Clothing Tag Examples:

Story US-37: Agency Client Performance Dashboards

As an agency user, I want per-client performance dashboards, So that I can report ROI to clients and justify the value of priority management services.

Acceptance Criteria:

• Each store in a multi-store account has its own performance dashboard (separate from the agency aggregate view)
• Dashboards can be shared via a read-only link that does not require an AdPriority login
• Shared links are branded with the agency’s name (or white-labeled on Enterprise tier)
• Dashboard includes: priority distribution, ROAS by tier, before/after comparisons, and key metrics
• Data on shared dashboards updates automatically (no manual refresh needed)
• Shared links can be deactivated at any time
• Dashboard includes a “Powered by AdPriority” footer (removable on white-label plans)

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-20 (multi-store), US-10 (performance metrics), US-12 (before/after comparison)

Story US-38: Undo Priority Change

As a store owner, I want to undo a priority change, So that I can quickly revert mistakes without having to remember the previous value.

Acceptance Criteria:

• After changing a product’s priority, an “Undo” action is available for 30 seconds (toast notification with undo button)
• Clicking “Undo” reverts the product to its previous priority score
• The undo action is also recorded in the audit trail
• For bulk changes, the undo reverts the entire bulk operation (all affected products)
• Beyond the 30-second undo window, the user can view the audit trail and manually revert by clicking on a previous score entry
• The audit trail’s “Revert to this” action works for any historical score, not just the most recent

Priority: P2 (Nice to Have) Effort: Low Phase: Phase 2 Dependencies: US-01 (priority scoring), audit trail

Story US-39: Inventory-Aware Priority Adjustment

As a store owner, I want priorities to automatically adjust when inventory is critically low, So that I do not waste ad spend driving traffic to products that will sell out before the ads stop running.

Acceptance Criteria:

• User can enable inventory-aware priority adjustments
• User can set a low-inventory threshold (default: 3 units across all locations)
• When a product’s total inventory drops below the threshold, the system reduces its priority by a configurable amount (default: -2)
• When a product reaches zero inventory, the system sets its priority to 0 (Exclude)
• When inventory is restocked above the threshold, the system restores the product’s rule-based priority
• Inventory checks run at a configurable interval (default: every 6 hours, using Shopify inventory API)
• Inventory-based adjustments respect manual overrides (if the user has overridden a product, low inventory does not change it unless the user opts in)
• A dashboard indicator shows how many products have reduced priorities due to low inventory

Priority: P2 (Nice to Have) Effort: Medium Phase: Phase 2-3 Dependencies: US-01 (priority scoring), Shopify inventory API access (read_inventory scope)

3.9 Story Map

The story map organizes all stories by user activity (rows) and delivery phase (columns), showing the progressive expansion of functionality from MVP to full product.

STORY MAP: ACTIVITIES x PHASES
================================

                    Phase 0          Phase 1              Phase 2                Phase 3+
                    (Nexus MVP)      (SaaS Foundation)    (Full Product)         (Scale)
                    ============     ================     ================       ================

  SETUP &           Manual           US-30 Google         US-32 CSV              US-20 Multi-Store
  ONBOARDING        spreadsheet      US-34 Quick Setup    Import/Export          US-21 Rule Cloning
                    & scripts        US-31 Dashboard                             US-37 Client
                                                                                 Dashboards

  DAILY             Manual           US-01 Assign         US-07 Bulk Edit        US-11 ROAS
  PRIORITY          scoring          US-06 Manual         US-36 Tag Rules        Recommendations
  MANAGEMENT        via scripts      Override             US-35 Unscored
                                     US-38 Undo           Detection
                                                          US-39 Inventory-Aware

  RULES &           Category         US-02 Category       US-03 Seasonal         US-21 Rule Cloning
  AUTOMATION        mapping          Rules                US-04 New Arrival      (cross-store)
                    document                              Boost

  SYNC &            Manual Sheet     US-05 Sync Status    US-08 Preview          US-22 Per-Store
  MONITORING        creation         US-30 Google         US-33 Sync Alerts      Reports
                                     Connection

  ANALYTICS &       Manual ROAS      (basic sync stats    US-10 Tier Metrics     US-11 ROAS
  REPORTING         measurement      in dashboard)        US-12 Before/After     Recommendations
                    in Google Ads                                                US-37 Client
                                                                                 Dashboards

Reading the Story Map

• Left to right: Each column represents increasing product maturity. Phase 0 is a manual validation; Phase 3+ is a fully automated, multi-tenant SaaS product.
• Top to bottom: Each row represents a distinct user activity. The most critical activities (Setup, Daily Management) are at the top.
• Phase 1 stories are the minimum viable product for the SaaS launch. Without these, the app cannot function.
• Phase 2 stories are the differentiators that justify the Growth tier pricing and set AdPriority apart from manual CSV workflows.
• Phase 3+ stories are the scale features that justify Pro/Enterprise pricing and agency adoption.

3.10 Priority Matrix

By Priority Level

By Effort Level

Priority vs. Effort Matrix

PRIORITY vs. EFFORT MATRIX
============================

              Low Effort          Medium Effort           High Effort
              ===========         =============           ===========

  P0          --                  US-01 Assign            US-02 Category Rules
  (Must)                          US-06 Override          US-05 Sync Status
                                  US-31 Dashboard         US-30 Google Connect
                                                          US-34 Quick Setup

  P1          US-35 Unscored     US-07 Bulk Edit         US-03 Seasonal Auto
  (Should)                        US-04 New Arrival
                                  US-32 CSV Import
                                  US-33 Sync Alerts
                                  US-36 Tag Rules

  P2          US-38 Undo         US-08 Preview           US-10 Tier Metrics
  (Nice)                          US-39 Inventory         US-12 Before/After

  P3          --                  US-22 Reports           US-11 Recommendations
  (Future)                                                US-20 Multi-Store
                                                          US-21 Rule Cloning
                                                          US-37 Client Dashboards

Strategic Insight: The P0 stories are a mix of medium and high effort, which is expected for foundational features. The two low-effort stories (US-35, US-38) are quick wins that can be added to any sprint without significant schedule impact. The P3 stories are predominantly high-effort, which aligns with their “future” classification – they require the mature platform that earlier phases build.

3.11 Story Dependencies

Dependency Graph

STORY DEPENDENCY GRAPH
=======================

  [Product Import from Shopify]  <-- Infrastructure prerequisite (not a story)
         |
         v
  US-01 Assign Priority Scores
         |
         +----------+-----------+-----------+
         |          |           |           |
         v          v           v           v
  US-02 Category   US-06      US-05       US-31
  Rules            Override    Sync        Dashboard
         |          |          Status
         |          |           |
         +----+-----+           +----+
         |    |                 |    |
         v    v                 v    v
  US-03 Seasonal    US-07      US-08     US-33
  Automation        Bulk Edit  Preview   Sync Alerts
         |
         v
  US-04 New Arrival Boost


  [Google OAuth]  <-- Infrastructure prerequisite
         |
         v
  US-30 Google Account Connection
         |
         v
  US-34 Quick Setup (Onboarding)


  [Google Ads API]  <-- Infrastructure prerequisite
         |
         v
  US-10 Priority Tier Metrics
         |
         +----------+
         |          |
         v          v
  US-11 ROAS       US-12 Before/After
  Recommendations  Comparison


  US-20 Multi-Store Dashboard
         |
         +----------+-----------+
         |          |           |
         v          v           v
  US-21 Rule       US-22       US-37
  Cloning          Reports     Client Dashboards

Critical Path

The critical path for the Phase 1 launch follows this sequence:

CRITICAL PATH (Phase 1)
========================

  Product Import --> US-01 --> US-02 --> US-05 --> US-30 --> US-34 --> US-31
                     Assign    Category   Sync      Google    Quick     Dashboard
                     Scores    Rules      Status    Connect   Setup

  Estimated Duration: 4-6 weeks (parallel work possible on US-30)

Parallel Tracks: US-30 (Google account connection) can be developed in parallel with US-01 and US-02 because it depends on infrastructure (OAuth), not on the scoring features. US-06 (manual override) can be built alongside US-02. US-31 (dashboard) can be started once US-01 provides data to display.

Dependency Rules

1. No story can be deployed without US-01 – priority scoring is the foundation of every other feature
2. No sync feature can work without US-30 – Google account connection is required for the supplemental feed pipeline
3. No analytics feature can work without US-10 – performance tier metrics require Google Ads API data
4. No multi-store feature can work without US-20 – the multi-store dashboard is the prerequisite for all agency features
5. Seasonal automation (US-03) requires category rules (US-02) – seasonal scores are applied per category group

3.12 Validation with Nexus Clothing

Phase 0 uses Nexus Clothing as a live test case to validate the core stories before investing in SaaS infrastructure. Not all stories are validated in Phase 0 – only those that prove the fundamental value proposition.

Stories Validated in Phase 0

Stories Deferred to Phase 1+

Nexus-Specific Validation Criteria

Success Metrics Per Story

PHASE 0 STORY VALIDATION TARGETS
==================================

  US-01 (Assign Priorities)
  -------------------------
  Target: Every active product has a score between 0 and 5
  Measurement: COUNT(*) WHERE priority IS NOT NULL = 2,425
  Validation: Distribution looks reasonable (not all products at one score)

  Expected Distribution:
    Priority 5: ~300 products  (12%)  -- Seasonal peaks, new arrivals
    Priority 4: ~500 products  (21%)  -- Strong performers, brand names
    Priority 3: ~800 products  (33%)  -- Year-round staples
    Priority 2: ~400 products  (16%)  -- Low-season, low-margin
    Priority 1: ~200 products  (8%)   -- End of season, slow movers
    Priority 0: ~225 products  (10%)  -- Out of stock, discontinued (active only)
    Note: 3,121 archived + 36 draft products also get priority 0 but are separate

  US-02 (Category Rules)
  ----------------------
  Target: 20 category groups cover all 90 product types with zero unmapped types
  Measurement: Every product_type in the catalog maps to exactly one category group
  Validation: Store owner reviews each group and confirms the mapping

  US-05 (Sync Status)
  -------------------
  Target: 100% of active variants appear in supplemental feed
  Measurement: Row count in Google Sheet matches active variant count
  Validation: GMC processing report shows matched products = total rows, errors = 0

Summary

This chapter defined four user personas, 24 user stories, and the relationships between them.

Personas: Sarah (small store owner, Starter tier), Marcus (growing brand manager, Growth tier), Diana (agency account manager, Pro/Enterprise tier), and Will (Nexus Clothing owner, Phase 0 validation). Each persona has distinct pain points and uses AdPriority differently, but all share the same core need: automating the assignment of Google Ads product priorities.

Stories: 7 P0 stories form the minimum viable product (Phase 1). 7 P1 stories deliver the seasonal automation and rules engine that differentiate AdPriority (Phase 2). 5 P2 stories add analytics and quality-of-life features (Phase 2-3). 5 P3 stories enable multi-store agency management (Phase 3+). An additional 10 discovered stories (US-30 through US-39) fill gaps in onboarding, monitoring, and workflow efficiency.

Critical Path: Product import feeds US-01 (assign priorities), which feeds US-02 (category rules), which feeds US-05 (sync status). In parallel, US-30 (Google account connection) enables the sync pipeline. Together, these form the minimum viable product that Phase 1 must deliver.

Validation: Phase 0 validates the five most critical stories (US-01, US-02, US-03, US-05, US-36) using Nexus Clothing as a live test case with 5,582 products, 90 product types, and 124,060 GMC variants. Success is defined as 100% product scoring, accurate category mapping, and a 15%+ ROAS improvement within 30 days.