joomcode · fiharet34 · Aug 7, 2026
@@ -1,25 +1,27 @@
 ---
 name: seller-copilot
 description: >
-  Deeper Mercado Livre (Brasil) seller analyses on JoomPulse data, beyond what a
-  single skill in this repo answers: real margins and ML fees ("minha margem
-  real", "how much do I actually make", "taxas do ML"); pricing and price wars
-  ("qual preço cobrar", "estou caro?"); is a product worth selling ("devo vender
-  este produto", "vale a pena"); finding new products ("o que vender agora");
-  vetting a supplier catalogue and import-vs-domestic ("vale a pena importar");
-  fixing a listing that does not sell ("meu anúncio não vende", "melhorar meu
-  anúncio"); who my competitors are and where I lose to them ("quem são meus
-  concorrentes", "onde estou perdendo", "o que eles vendem que eu não vendo");
-  market structure ("quem domina a categoria"); trends and when to stock
-  ("quando estocar", "sazonalidade"). Also takes vague or multi-part requests
-  ("me ajuda a crescer", "por onde começo") and asks one or two questions first.
-  Sales and revenue are JoomPulse estimates, not real transactions.
+  Deeper Mercado Livre (Brasil) and Shopee Brasil seller analyses on JoomPulse
+  data, beyond what a single skill in this repo answers: real margins and fees
+  ("minha margem real", "taxas do ML"); pricing and price wars ("qual preço
+  cobrar", "estou caro?"); is a product worth selling ("vale a pena vender
+  isso"); finding new products ("o que vender agora"); vetting a supplier and
+  import-vs-domestic ("vale a pena importar"); a listing that does not sell
+  ("meu anúncio não vende"); who my competitors are and where I lose to them
+  ("quem são meus concorrentes", "onde estou perdendo"); market structure ("quem
+  domina a categoria"); trends and when to stock ("quando estocar",
+  "sazonalidade"). Covers both marketplaces, including Shopee ("vender na
+  Shopee", "minha loja na Shopee"), and asks which one when unclear. Also takes
+  vague or multi-part requests ("me ajuda a crescer", "por onde começo") and
+  asks one or two questions first. Sales and revenue are JoomPulse estimates,
+  not real transactions.
 ---
 
 # Seller Copilot
 
-This skill is the **consultant front door** for Mercado Livre (Brasil) sellers working
-with JoomPulse data. It handles two kinds of request that a single focused skill does not:
+This skill is the **consultant front door** for sellers working with JoomPulse data, on
+**both marketplaces it covers — Mercado Livre (Brasil) and Shopee Brasil**. It handles two
+kinds of request that a single focused skill does not:
 
 1. **Vague or compound questions** — "help me grow my store", "por onde começo", "analisa
    minha operação" — where the seller does not yet know which analysis they need.
@@ -34,7 +36,12 @@ consolidated, verdict-first answer**.
 
 ## When to use another skill instead
 
-If the request maps cleanly onto a single focused skill in this repo, use that skill —
+**Only for Mercado Livre.** Every focused skill in this repo is Mercado Livre only, so
+handing a **Shopee** question to one returns Mercado Livre data to a Shopee seller — a wrong
+answer that looks right. For Shopee there is nothing to defer to: do the analysis here, from
+the `references/shopee-*` files.
+
+For a Mercado Livre request that maps cleanly onto a single focused skill, use that skill —
 it is faster and more direct. In particular:
 
 - One category's opportunity snapshot → **category-opportunity-index**
@@ -64,10 +71,15 @@ MCP setup before it can analyse marketplace data.
 
 ## Scope
 
-- **Mercado Livre (Brasil) only.** The analyses here cover Mercado Livre Brasil. If the
-  seller asks about another marketplace, say that it falls outside what **this skill**
-  does — do not claim JoomPulse holds no data for it, which may not be true — and still
-  answer the Mercado Livre part in full, rather than refusing the whole request.
+- **Mercado Livre (Brasil) and Shopee Brasil.** Both are covered, with different depth —
+  see [which-marketplace.md](references/which-marketplace.md). Any other marketplace falls
+  outside what this skill does; say so and still answer the in-scope part in full.
+- **Never mix the two marketplaces in one query, table or total.** They are separate
+  datasets with different grains and estimate methods; a combined figure is a wrong number,
+  not a fuller picture. Comparing them means two analyses side by side, in prose.
+- **Shopee coverage is narrower.** No keyword data, no seasonality or long-run trend
+  (history begins May 2026), no buy-box, no medals, no fee data. Name the gap rather than
+  answering it from Mercado Livre.
 - **Sales, orders, revenue and GMV are JoomPulse estimates**, not real transactions.
 - **Real marketplace history**, by contrast: price, rating and review counts, and a seller's
   reputation, medal, cancellation rate and completed-sales counters. Do not label these
@@ -86,6 +98,24 @@ MCP setup before it can analyse marketplace data.
 
 ## How to use this skill
 
+### Step 0 — Settle the marketplace first
+
+Before any analysis, know which marketplace the question is about. Getting this wrong wastes
+the whole analysis and hands the seller figures for a market they do not sell on.
+
+- The seller said so → take them at their word.
+- An identifier beginning **`MLB`**, or a `mercadolivre.com.br` link → Mercado Livre. A **bare
+  10–11 digit number**, or a `shopee.com.br` link → Shopee.
+- The request only makes sense on one of them — buy-box, medals, keywords, fulfilment
+  programme are Mercado Livre concepts → Mercado Livre.
+- **Otherwise ask, in one short question, before querying.** Do not guess and do not default
+  to Mercado Livre because it is the richer dataset.
+
+Read [which-marketplace.md](references/which-marketplace.md) whenever the answer is not
+immediate, the seller mentions both, or the request assumes a capability one marketplace
+lacks. It carries the full capability comparison and how to handle a genuine both-marketplace
+request.
+
 ### Step 1 — Classify the request
 
 Place it in exactly one of these:
@@ -135,6 +165,10 @@ Pick the **minimal set** that answers the question. Read the matching file in
 `references/` and follow its procedure. Run them in this same conversation, one after
 another; there is no need to announce the internal steps to the seller.
 
+**The tables below are for Mercado Livre.** For a Shopee request, use the Shopee table further
+down instead — the procedures differ, and the Mercado Livre files assume mechanics and data
+Shopee does not have.
+
 **What to sell**
 
 | The question | Read |
@@ -172,6 +206,24 @@ another; there is no need to announce the internal steps to the seller.
 | Rank the sellers / brands in a category | the **top-sellers-in-category**, **top-brand-position-tracker** skills |
 | What changed since last period? | the **category-monitor**, **product-change-monitor** skills — each needs a previous snapshot from the seller |
 
+**Shopee**
+
+Use these instead of everything above when the marketplace is Shopee. There are no focused
+Shopee skills to defer to.
+
+| The question | Read |
+|---|---|
+| Is this category worth entering? | `references/shopee-category-evaluation.md` |
+| Who dominates this category? How concentrated is it? | `references/shopee-market-structure.md` |
+| What should I sell? | `references/shopee-find-new-products.md` |
+| Is *this specific* item worth selling? | `references/shopee-validate-product.md` |
+| How has this item been selling over time? | `references/shopee-item-momentum.md` |
+| Who are my competitors? | `references/shopee-discover-competitors.md` |
+| Tell me about this shop | `references/shopee-competitor-profile.md` |
+| What do they sell that I don't? How do prices compare? | `references/shopee-assortment-and-price-gaps.md` |
+| What price should I charge? | `references/shopee-pricing.md` |
+| Keywords, seasonality, when to stock, buy-box, medals, fees, margin | **Not available on Shopee** — name the gap, offer the nearest real alternative, and never answer it from Mercado Livre data. See [which-marketplace.md](references/which-marketplace.md) |
+
 **Caveats that must survive a handoff**
 
 Handing work to a focused skill is usually the right call — it is faster and more direct. But a
@@ -219,7 +271,25 @@ the refined request — no need to re-classify unless the topic changed.
 ## Reference files
 
 Each file documents one analysis procedure. Read the one you need; they are not meant to
-be read all at once.
+be read all at once. Files prefixed `shopee-` are Shopee Brasil; the rest are Mercado Livre.
+
+- [Which marketplace?](references/which-marketplace.md) — how to decide, what each
+  marketplace can and cannot answer, and how to handle a request spanning both. **Read this
+  first whenever the marketplace is not obvious.**
+
+**Shopee Brasil**
+
+- [Category evaluation](references/shopee-category-evaluation.md),
+  [market structure](references/shopee-market-structure.md),
+  [find new products](references/shopee-find-new-products.md),
+  [validate a product](references/shopee-validate-product.md),
+  [item momentum](references/shopee-item-momentum.md),
+  [discover competitors](references/shopee-discover-competitors.md),
+  [shop profile](references/shopee-competitor-profile.md),
+  [assortment and price gaps](references/shopee-assortment-and-price-gaps.md),
+  [pricing](references/shopee-pricing.md).
+
+**Mercado Livre (Brasil)**
 
 - [Margin and fees](references/margin-and-fees.md) — net margin from public ML fee tables
   plus seller-supplied costs; what each fee takes.

@@ -0,0 +1,84 @@
+# Assortment and price gaps on Shopee
+
+What competitors sell that the seller doesn't, and how the two price ranges line up. Two
+questions that are usually asked together and should be answered together.
+
+## What to ask for
+
+- **The seller's own range** — their shop, or a list of what they sell. Without it there is no
+  gap analysis; ask rather than guessing.
+- **The competitor set** — from [shopee-discover-competitors.md](shopee-discover-competitors.md) if not already
+  established, or a shop the seller names.
+- **The category** to bound the comparison.
+
+## Method — the gap side
+
+1. Pull the competitor's items in the bounded category.
+2. Pull the seller's own items in the same category.
+3. **Sort the gaps by estimated revenue, not by count.** A gap only matters if the missing item
+   actually earns. Twenty missing products that sell nothing are not a finding.
+4. For each candidate gap, sanity-check demand the way
+   [shopee-validate-product.md](shopee-validate-product.md) does before recommending it. A gap is not
+   automatically an opportunity.
+
+**Three items a competitor earns well from, which the seller could plausibly source, is a better
+answer than forty items they cannot.**
+
+## Method — the price side
+
+Use the **whole distribution**, not the average. An average is dragged around by outliers and
+hides where the market actually transacts.
+
+- Where do the seller's prices sit against the competitor's range — below, inside, above?
+- Where in the range do **units** actually move? That is the meaningful band, and it is often not
+  the cheapest end.
+- **Read the price history** before advising. An item whose price has drifted steadily downwards
+  is in a race to the bottom, and the advice changes from "match the price" to "compete on
+  something other than price".
+
+Price history is available as intervals — a price and the span it held — and is **item-level
+only**, so never claim a particular variant, size or colour moved.
+
+## Interpreting the two together
+
+- **A gap at a price band the seller already serves** — the easiest win; they know the buyer.
+- **A gap at a band they don't serve** — a real decision, not a quick add. Say what entering that
+  band would require.
+- **No gaps, but a price disadvantage** — the answer is pricing, not assortment. Hand off to
+  [shopee-pricing.md](shopee-pricing.md) rather than inventing assortment advice.
+- **Gaps everywhere and no price disadvantage** — usually means the competitor is simply larger.
+  Say so; "add forty products" is not advice.
+
+## Procedure
+
+1. Bound the category and **pin one level**.
+2. Read the competitor's items and the seller's, in that same bounded scope.
+3. Difference the two ranges; sort candidates by estimated revenue.
+4. Build the price distribution for both sides and locate where units move.
+5. Check the price history of the contested items.
+6. Validate the top gap candidates before recommending them.
+
+## Output
+
+**Verdict first:** the single gap worth acting on, and whether the seller's pricing is helping or
+hurting.
+
+Then two views — the gap table (item, estimated sales and revenue, price, why it matters) and the
+price comparison showing both ranges and where units concentrate. Cap the gap table at ten rows
+by default, state the total, and **never pad it to reach a round number**.
+
+State the estimate disclaimer once. Use full BRL precision. Show `—` for unavailable values.
+
+## Boundaries
+
+- **Without the seller's own range there is no gap analysis.** Ask for it; do not assume a
+  catalogue.
+- **Sales and revenue are estimates** from rounded counters; prices are real. Do not rank gaps on
+  small estimated differences.
+- **Tracked items only** — a competitor may carry products that have never sold and are therefore
+  invisible here, so the assortment view is a lower bound, not their full catalogue.
+- **No per-variant view.** A competitor's size or colour range is not visible; do not infer it.
+- **No catalogue or buy-box**, so "the same product" is a judgement about comparable items rather
+  than a platform fact. Say which items you treated as comparable.
+- **A gap is not automatically an opportunity** — the seller may be unable to source it, or may
+  have dropped it deliberately. Ask before assuming it is an oversight.
@@ -0,0 +1,92 @@
+# Evaluate a Shopee category
+
+Is this category worth entering? Judged on demand, competition and room to earn — not on size
+alone.
+
+## What to ask for
+
+- **The category**, at whatever depth the seller has in mind, or a list to compare.
+- If free text matches several plausible categories, **list the candidates with their level and
+  let the seller pick** — never guess between unrelated categories. Shopee's Brazilian taxonomy
+  does not group things the way sellers often expect; electronics in particular is split across
+  several separate top-level categories rather than sitting under one.
+
+## The two constraints that shape every answer here
+
+**Only three levels of category analytics exist.** Anything deeper is counted at its
+third-level ancestor. So "find me a tiny sub-niche" is not answerable at the analytics level —
+say so, and offer the item-level view in [shopee-find-new-products.md](shopee-find-new-products.md) instead,
+which does reach deeper.
+
+**Every level carries its whole subtree.** A parent's figures already contain all of its
+children's, by construction. **Adding levels together counts the same sales several times over
+— roughly threefold.** Confine any total, ranking or comparison to a single level, and say
+which level you used.
+
+## The screening rubric
+
+Judge a category on four things:
+
+- **Opportunity tier** — the composite signal of an under-exploited category, combining
+  concentration, saturation and earnings per seller. High is the shortlist; low is a warning.
+- **Concentration** — how tightly GMV is held across sellers. Low or medium means the field is
+  open. See [shopee-market-structure.md](shopee-market-structure.md) for what the index does and does not mean.
+- **Earnings per seller** — reported as a tier judged against other categories under the same
+  top-level parent, which is more useful than an absolute figure. Prefer the tier.
+- **Growth month over month** — the only growth signal available.
+
+**Do not carry over absolute currency thresholds from another marketplace.** Shopee Brasil is a
+different market with a different size distribution and a different badge-award rate, so a
+revenue floor that means "substantial" elsewhere means something else here. Judge a category
+**relative to its siblings** — other categories at the same level under the same parent — and
+say that is the comparison you made. If you need an absolute floor, derive it from the sibling
+distribution in the same answer rather than asserting one.
+
+Use it as a rubric, not a checklist: a category can miss one criterion and still be worth
+entering if the seller has a specific edge. Say which criterion it misses and what the edge
+would have to be.
+
+## Confirm from more than one angle
+
+- **Seller mix** — how much of the category is held by official (Mall) and preferred shops
+  versus regular sellers. A category that is mostly regular sellers is still developing.
+- **Cross-border share** — how much of the category is served from outside Brazil. A high share
+  changes who the seller is really competing with, and on what lead time.
+- **Item counts and how they moved** — a category adding items faster than it adds revenue is
+  getting more crowded, not more attractive.
+
+## Procedure
+
+1. Resolve the category and confirm its level.
+2. Pull the latest month's figures for that category **at one pinned level**, and the previous
+   month for the month-over-month read.
+3. Rank or compare candidates **by the rubric, not by revenue alone**, against same-level
+   siblings.
+4. Check the seller mix and cross-border share before concluding.
+5. **Confirm the month on the rows you got back.** A marker for "current period" is unreliable
+   here — read the date rather than trusting the marker.
+
+## Output
+
+**Verdict first, in plain language** — enter, enter with a condition, or avoid — then the
+opportunity view: the category against its siblings on demand, concentration, earnings per
+seller and growth, banded so the shape reads at a glance. When comparing several categories,
+rank them and say which one you would pick and why.
+
+Say which level you compared at. Never fabricate a missing value — show `—`. State the estimate
+disclaimer once. Use full BRL precision.
+
+## Boundaries
+
+- **Revenue and order figures are estimates**, rebuilt from Shopee's rounded public sold
+  counters. Small differences between categories are noise.
+- **Month-over-month is the only trend available.** There is no longer-run trend and no
+  seasonal shape — the history begins in May 2026 and is too short. If asked whether a category
+  is seasonal, say the data cannot answer it yet rather than reading a season into two or three
+  months.
+- **Three levels only.** Do not imply a deeper niche read than exists.
+- **Brand concentration is not computable** — coverage is a lower bound, so a category that
+  looks brand-free may simply have untracked brands.
+- Screening well is not the same as being winnable: a well-screening category can still contain
+  a locked-up niche, and one the seller knows nothing about is riskier than a slightly worse one
+  they understand.