Update to Advan Research REI

{
  "description": "Workflow for comparing a subject property to a retailer's or category's existing location footprint using Advan REI's retailer footprint endpoint. The endpoint aggregates all of a retailer's or category's locations within a defined radius of the subject site and compares them across foot traffic variables, demographics, shared customers, and demographic match score. Use this skill whenever a user wants to know how a property compares to a retailer's typical location, whether a site fits a retailer's footprint, how similar a candidate site is to where a retailer already succeeds, or wants to evaluate a retailer's presence in a market area. Trigger on phrases like \"how does this site compare to [retailer]'s locations\", \"does this fit [retailer]'s footprint\", \"retailer footprint\", \"how does this property benchmark against [retailer]\", or any request that involves comparing a site to a specific retailer's or category's existing locations. Also trigger as part of site selection when a specific retailer is named.\n",
  "included_files": [],
  "name": "retailer-footprint",
  "skill_md_contents": "---\nname: retailer-footprint\ndescription: >\n  Workflow for comparing a subject property to a retailer's or category's\n  existing location footprint using Advan REI's retailer footprint endpoint.\n  The endpoint aggregates all of a retailer's or category's locations within\n  a defined radius of the subject site and compares them across foot traffic\n  variables, demographics, shared customers, and demographic match score.\n  Use this skill whenever a user wants to know how a property compares to a\n  retailer's typical location, whether a site fits a retailer's footprint,\n  how similar a candidate site is to where a retailer already succeeds, or\n  wants to evaluate a retailer's presence in a market area. Trigger on\n  phrases like \"how does this site compare to [retailer]'s locations\",\n  \"does this fit [retailer]'s footprint\", \"retailer footprint\", \"how does\n  this property benchmark against [retailer]\", or any request that involves\n  comparing a site to a specific retailer's or category's existing locations.\n  Also trigger as part of site selection when a specific retailer is named.\n---\n\n# Retailer Footprint Workflow\n\nThis skill has two modes depending on whether the user has a subject site:\n\n- **Site comparison mode:** A subject site is provided. Compare it against\n  the retailer's or category's nearby locations to assess fit.\n- **Nationwide profile mode:** No subject site. Summarize the retailer's or\n  category's footprint nationally, with the option to compare across\n  geographies.\n\nDetermine the mode from context before proceeding. If a subject site has been\nestablished earlier in the conversation, default to site comparison mode. If\nthe user is asking about a retailer's footprint generally — \"what does\n[Retailer]'s typical location look like?\", \"how does [Retailer] perform\nnationally?\", \"walk me through [Retailer]'s footprint\" — use nationwide\nprofile mode.\n\n---\n\n## Mode A: Site Comparison\n\n### Step 1: Confirm the Inputs\n\nTwo inputs are required before calling the endpoint. If either is missing,\nask — don't proceed with assumptions.\n\n**Subject site:** Resolve using ALI, location name, and company name as usual.\n\n**Retailer or category:** Who are we comparing against? This could be a\nspecific brand (Trader Joe's, TJ Maxx) or a broader category (grocery,\noff-price apparel, fitness). If the user named one, use it. If the request\nis ambiguous — \"how does this compare to similar retailers\" — ask them to\nspecify before proceeding.\n\n**Date range:** Use the UI selection or whatever the user specified.\n\n**Distance:** Default is 100 miles. Don't change it yet — Step 2 will\ndetermine whether an adjustment is warranted after seeing how many locations\nthe endpoint returns.\n\n---\n\n## Step 2: Call the Endpoint and Assess the Footprint Size\n\nCall the retailer footprint endpoint with the subject site, retailer/category,\n100-mile radius, and date range.\n\nBefore interpreting the results, check how many locations were returned.\nFootprint size directly affects how reliable the aggregate comparison is.\n\n### Too few locations (fewer than 5)\n\nA comparison built on fewer than 5 locations is statistically fragile — one\nunusual store can skew the entire aggregate. Flag this to the user and\nrecommend widening the radius before drawing conclusions.\n\n> \"The 100-mile radius only captured 3 [Retailer] locations, which may not\n> give a reliable picture of their typical footprint. I'd suggest widening\n> to 150 or 200 miles for a more stable comparison — want me to rerun it?\"\n\nDon't present the comparison results as meaningful if the location count is\nthis low unless the user explicitly wants to proceed anyway.\n\n### Healthy footprint (5–30 locations)\n\nThis is the reliable range. Proceed to interpretation.\n\n### Large footprint (more than 30 locations)\n\nA large footprint isn't necessarily a problem — a national retailer with\ndense coverage may legitimately have 50+ locations in range. But it's worth\nflagging that the aggregate is averaging across a wide geography and possibly\ndiverse market types, which can mask variation. Note the count, proceed with\nthe comparison, and proactively offer location-level data so the user can\nsee the distribution if the aggregate picture feels too averaged.\n\n> \"There are 47 [Retailer] locations within 100 miles — the footprint\n> comparison reflects a broad average across diverse markets. I can also\n> pull individual location data if you want to see which specific stores\n> are most similar to this site.\"\n\n---\n\n## Step 3: Interpret the Comparison Results\n\nThe endpoint compares the subject site against the retailer footprint across\nseveral dimensions. Here's how to read each one:\n\n**Overall demographic match score:** The headline fit signal. A high match\nmeans the subject site's visitor profile resembles the retailer's typical\ncustomer base. A low score doesn't automatically disqualify the site — it\nmay mean the retailer hasn't tapped this customer type yet — but it warrants\nexplanation.\n\n**Foot traffic variables (visits, dwell time, visit frequency, hour/day\npatterns):**\n- *Visit volume:* Is the subject site attracting traffic at a level comparable\n  to the retailer's typical locations? Significantly lower volume may indicate\n  the site underperforms as a draw; significantly higher may signal strong\n  opportunity or a different use pattern.\n- *Dwell time:* A subject site with lower dwell than the retailer's footprint\n  suggests visitors aren't spending the kind of time the retailer's model\n  typically requires. This is a meaningful signal for retailers that depend\n  on browse time (specialty, home goods, apparel).\n- *Visit frequency:* A site with lower frequency than the retailer's footprint\n  may not generate the repeat customer pattern the retailer depends on —\n  especially relevant for grocery, fitness, and other high-frequency\n  categories.\n- *Hour and day patterns:* Does the subject site peak at the same times as\n  the retailer's typical locations? A mismatch here — a site that peaks\n  weekday mornings vs. a retailer that depends on weekend afternoon traffic —\n  is a behavioral fit concern even if volume looks fine.\n\n**Shared customers:** What percentage of the subject site's visitors also\nvisit the retailer's nearby locations? High shared customers means the\nretailer is already drawing from this trade area — which could indicate\nstrong demand, or that an existing nearby location may cannibalize a new one.\nLow shared customers may indicate an untapped customer pool or a genuinely\ndifferent visitor base.\n\n**Reading convergent vs. divergent signals:**\n- Strong match across demographics, traffic behavior, and shared customers →\n  high-confidence fit. The site looks like the retailer's wheelhouse.\n- Strong demographic match but divergent traffic behavior → the customer is\n  there, but the site doesn't drive the behavior the retailer's model relies\n  on. Worth flagging as a risk.\n- Strong traffic behavior match but low demographic match → the location\n  performs similarly, but the customer profile differs. May work depending\n  on the retailer's flexibility, but flag the divergence.\n- Low shared customers + strong demographic match → the retailer may not have\n  meaningful penetration in this trade area. Could be opportunity, could be\n  an indication the customer here behaves differently than expected.\n- Low across all dimensions → be direct. The site doesn't profile as a strong\n  fit based on the available data.\n\n---\n\n## Step 4: Offer Location-Level Data (When Warranted)\n\nProactively offer individual location data in these situations:\n\n- The footprint is large (30+ locations) and the aggregate may be masking\n  useful variation\n- The comparison results are mixed or show meaningful divergence on some\n  dimensions — knowing which specific locations are closest to the subject\n  site helps calibrate the finding\n- The user is trying to identify the most analogous existing location (useful\n  for site visits, case studies, or leasing conversations)\n- Cannibalization risk is a concern — seeing the individual nearby locations\n  and their traffic profile is more useful than an aggregate\n\nWhen pulling individual location data, surface the locations ranked by\nsimilarity to the subject site on the dimensions that matter most for the\nuser's question.\n\n---\n\n## Step 5: Present Results\n\n### Lead with the headline fit assessment\n\nOne clear sentence on overall fit based on the convergent signals.\n\n> \"On balance, [Subject Site] profiles as a strong fit for [Retailer] —\n> the demographic match is high, dwell time and frequency are consistent\n> with their footprint, and the traffic pattern aligns with their peak\n> periods.\"\n\nOr if the picture is mixed:\n\n> \"[Subject Site] matches [Retailer]'s demographic profile well but shows\n> meaningfully lower visit frequency than their typical locations — worth\n> considering for a retailer that depends on repeat traffic.\"\n\n### Comparison summary table\n\nAlways include these four dimensions — they are the core fit signals:\n\n| Dimension | Subject Site | Retailer Footprint Avg | Assessment |\n|-----------|-------------|----------------------|------------|\n| Demographic match | X | — | High / Med / Low |\n| Avg dwell time | X min | X min | At / Above / Below footprint |\n| Avg visit frequency | X | X | At / Above / Below footprint |\n| Shared customers | X% | — | High / Moderate / Low |\n\nIf the data supports it and the user's question warrants it, extend the\ntable with additional dimensions:\n\n| Dimension | Subject Site | Retailer Footprint Avg | Assessment |\n|-----------|-------------|----------------------|------------|\n| Peak day of week | [Day] | [Day] | Aligned / Divergent |\n| Peak hour | [Hour] | [Hour] | Aligned / Divergent |\n| Visits by radius (1/3/5 mi) | X / X / X | X / X / X | At / Above / Below footprint |\n| Visits by drive time (5/10/15 min) | X / X / X | X / X / X | At / Above / Below footprint |\n| Distance to nearest footprint location | X mi | — | — |\n\nAdd the extended rows when visit timing or proximity to existing locations\nis relevant to the user's question — site selection, cannibalization\nevaluation, or when the core table shows a divergence that the time/day\npattern might explain. Skip them when the core four tell a clear enough\nstory on their own.\n\n### Narrative\n\nTwo to three sentences connecting the dimensions into a coherent read.\nHighlight where signals converge and call out any meaningful divergences.\nReference the footprint location count so the user knows how robust the\ncomparison is.\n\n### Cite data vintage and footprint parameters\n\n> *Comparison based on [date range] using [N] [Retailer] locations within\n> [X] miles, via Advan's mobile device panel.*\n\n---\n\n## Mode B: Nationwide Profile (No Subject Site)\n\nUse this mode when the user wants to understand a retailer's or category's\nfootprint in general — not in comparison to a specific property.\n\n### Step 1: Confirm the Retailer or Category\n\nConfirm who the user wants to profile. If a specific brand or category hasn't\nbeen named, ask before proceeding.\n\n**Date range:** Use the UI selection or whatever the user specified.\n\n### Step 2: Pull and Summarize the Nationwide Footprint\n\nCall the endpoint without a subject site to retrieve the nationwide profile.\nSummarize the retailer's or category's typical location characteristics\nacross the core dimensions:\n\n- **Traffic profile:** Average visits, dwell time, and visit frequency across\n  locations. Note the range if there's meaningful variation.\n- **Peak patterns:** Typical peak day of week and hour — this characterizes\n  the retailer's operational pattern (destination weekend shopper vs. weekday\n  convenience stop, etc.).\n- **Demographic profile:** The typical customer across the full set of\n  dimensions: median household income, dominant age cohort, primary\n  ethnicity/race composition, educational attainment, population density\n  of the trade area (urban core, suburban, exurban), and standout lifestyle\n  segments that define the retailer's core customer base.\n- **Visit distribution by radius and drive time:** How far the typical\n  customer travels. This characterizes the retailer as a convenience,\n  neighborhood, or destination concept.\n- **Location count and geographic spread:** How many locations are in the\n  dataset and whether coverage is national, regional, or concentrated.\n\n### Step 3: Offer Geographic Comparison\n\nAfter presenting the national summary, offer to break it down by geography.\nThis is most useful when the user is evaluating a specific market, comparing\nregions, or assessing whether the retailer performs differently across market\ntypes.\n\n> \"That's the national picture. Want me to compare how [Retailer] performs\n> across specific markets or regions — for example, how their Northeast\n> locations compare to their Sun Belt footprint?\"\n\nGeographic comparisons to offer based on context:\n- **Metro vs. metro:** How does [Retailer] perform in [Market A] vs.\n  [Market B]?\n- **Regional:** How does the Northeast footprint compare to the Southeast,\n  Midwest, or West?\n- **Urban vs. suburban vs. exurban:** Does the retailer's profile shift\n  meaningfully by market density?\n- **Custom geography:** If the user specifies a region, state, or set of\n  markets, pull and compare those directly.\n\n### Step 4: Present the National Summary\n\n### Headline\n\nOne sentence characterizing the retailer's typical location.\n\n> \"[Retailer] operates primarily as a [destination / neighborhood /\n> convenience] concept, drawing customers from a [X]-minute drive on average,\n> with a customer base skewing [demographic summary] and peak traffic on\n> [day/time].\"\n\n### National footprint table\n\n| Dimension | Retailer Avg |\n|-----------|-------------|\n| Avg monthly visits | X |\n| Avg dwell time | X min |\n| Avg visit frequency | X |\n| Peak day | [Day] |\n| Peak hour | [Hour] |\n| Visits within 1/3/5 mi | X% / X% / X% |\n| Visits within 5/10/15 min drive | X% / X% / X% |\n| Median household income | $X |\n| Dominant age cohort | X–Y |\n| Primary ethnicity / race | [Top 1–2] |\n| Educational attainment | [e.g., College-educated majority] |\n| Population density | [Urban / Suburban / Exurban] |\n| Top lifestyle segments | [Top 2–3] |\n| Locations in dataset | N |\n\nIf geographic comparisons were requested, add a column per geography.\n\n### Cite data vintage\n\n> *Based on [date range] across [N] [Retailer] locations nationally, via\n> Advan's mobile device panel.*\n\n---\n\n## Follow-Ups\n\nFor site comparison mode, the most natural next steps are pulling individual\nlocation data (if not already done), running a void analysis to see where\nthis retailer ranks as a candidate for the center, or checking cannibalization\nrisk if shared customers came back high. For nationwide profile mode, a\ngeographic breakdown or a comparison against a specific candidate site are\nthe natural directions. Let the conversation lead.\n"
}