[2nd · after #41] Fix top-sellers-in-category: rank against real sales, and stop reading buy-box position as idle stock

skills/top-sellers-in-category/SKILL.md

@@ -3,8 +3,9 @@ name: top-sellers-in-category
 description: >
   Ranks the top sellers in one Mercado Livre (Brasil) category by estimated average monthly
   revenue via JoomPulse, and returns a downloadable leaderboard — per seller: estimated
-  monthly sales and revenue, 365-day completed sales, cancellation rate, sales trend, brands,
-  product counts, international shipping, and listing-type counts, with a JoomPulse link each.
+  monthly sales and revenue, 365-day completed sales, cancellation rate, month-over-month
+  sales growth, medal, brands, product counts, international shipping, and listing-type
+  counts.
   It can also track how the ranking moved: supply a previous-period leaderboard for the same
   category and it shows each seller's movement (rose / fell / new) plus the biggest movers.
   Triggers: "top sellers in this category", "biggest stores in a category", "rank sellers by
@@ -19,9 +20,9 @@ description: >
 This skill returns the **top sellers in one Mercado Livre (Brasil) category**,
 ranked by estimated average monthly revenue. For each seller it shows estimated
 average monthly sales and revenue, completed sales over the last 365 days,
-cancellation rate, sales trend, brands, how their products split between all
-listings and listings with sales, international shipping, and classic versus
-premium listing counts.
+cancellation rate, month-over-month sales growth, medal, brands, how their
+products split between all listings and listings with sales, international
+shipping, and classic versus premium listing counts.
 
 By default it produces **today's leaderboard** as a downloadable table. It can
 also show **how the ranking moved over time**: if you supply a previous-period
@@ -41,9 +42,9 @@ To rank brands rather than sellers, use the top-brand-position-tracker skill.
   produces a standalone leaderboard.
 - The available JoomPulse tools can find the sellers active in a category and
   return each seller's profile (estimated average monthly sales and revenue,
-  last-365-day completed sales, cancellation rate, sales trend, brands, listing
-  distribution, international shipping, classic and premium listing counts).
-  Seller medal — used to color the chart — and reputation are read when available.
+  last-365-day completed sales, cancellation rate, month-over-month sales growth,
+  seller medal, brands, listing distribution, international shipping, classic and
+  premium listing counts). Reputation is read when available.
 
 If JoomPulse MCP access is unavailable, stop and explain that the skill requires
 JoomPulse MCP setup before it can rank a category's sellers.
@@ -53,7 +54,8 @@ JoomPulse MCP setup before it can rank a category's sellers.
 - **Mercado Livre (Brasil) only.** Other marketplaces are out of scope.
 - **Sales and revenue are JoomPulse estimates** derived from historical listing
   data — not real transactions. Cancellation rate and last-365-day completed sales
-  are real history. Disclose the estimate caveat in every output.
+  are real history. Disclose the estimate caveat in every output. **Use the real
+  figures to sanity-check the estimated ones**, never the other way round.
 - **Read-only.** The skill never writes or modifies anything; it does not store the
   leaderboard — the user keeps the downloadable table and brings it back next period.
 - **Language:** detect the seller's language and respond in it. Default to pt-BR.
@@ -73,6 +75,38 @@ Rank the sellers by **estimated average monthly revenue**, highest first. Keep a
 sensible top (default about 50, up to about 100 on request), and treat the count
 as a cap — show fewer if fewer exist.
 
+**Check every row against real sales before ranking it.** The revenue figure is an
+estimate; completed sales over the last year are real. Two different problems hide
+here, and they need different handling — do not treat them alike:
+
+- **No real trading history.** A shop with a handful of listings and a seven-figure
+  monthly estimate against a few hundred completed sales, or none at all, is an
+  artifact of one listing with an odd counter rather than a business. **Move these
+  out of the ranking** into a short labelled group ("estimativa não confiável")
+  with the estimate, the real completed sales and the listing count side by side,
+  and say the ranking excludes them. Flagging them in a note while still ranking
+  them is not enough: it spends leaderboard positions on artifacts and pushes real
+  sellers out.
+- **A real business with an inflated estimate.** A seller with tens of thousands of
+  completed sales is a genuine operation even where the estimate runs several times
+  its real pace. **Keep it in the ranking** and say beside it that the estimate
+  looks high against real volume, so its position may be too generous. Excluding a
+  seller with real trading history because an estimate is imprecise removes a
+  competitor the seller actually faces — a worse error than showing them too high.
+
+The distinction is the **real** figure, not the ratio: near-zero completed sales
+means exclude, substantial completed sales means keep and caveat. Say how many
+shops you examined to fill the ranking.
+
+**Name the shops that look like one company.** The ranking is of shops, not
+companies, and a retailer may run several storefronts — a shared name with regional
+suffixes is the usual tell. Where two or more rows share a name stem, group them in
+a short note, give the combined estimated revenue, and say plainly whether that
+combination would change the leader or the leader's share. **Do not assert common
+ownership**: it is not verifiable here, and unrelated registration dates and
+identifiers argue against a single operator as often as for one. Present it as an
+alternative reading of the same rows, and leave the ranking itself by shop.
+
 ### Step 3 — Present today's leaderboard and offer it for download
 
 Render the leaderboard for **today** (head it with the category name and the date).
@@ -100,10 +134,37 @@ Respond in the seller's language (default pt-BR).
 
 **Leaderboard (always):** a markdown table, plus a downloadable `.csv` / `.xlsx`:
 
-| Vendedor | Vendas méd. (mês) | Receita média (mês) | Vendas 365d | Cancel rate | Sales trend | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Classic | Premium |
-|---|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|
-
-- The **Vendedor** name links to the seller's JoomPulse page.
+| Vendedor | Medalha | Vendas méd. (mês) | Receita média (mês) | Vendas 365d | Taxa de cancelamento | Crescimento mensal | Marcas | Produtos (todos) | Produtos (com venda) | Envio internacional | Clássico | Premium |
+|---|:--|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|--:|
+
+- **The Vendedor name is plain text.** Sellers have no JoomPulse page — the
+  dashboard link template is for listing ids only — so a URL built from a shopId
+  404s. Headers are pt-BR by default; translate them only when the seller writes
+  in another language.
+- **Full precision in the money columns** — `R$ 1.279.436,00`, never `R$ 1,28 mi`.
+  This is a ranking: rounding collapses the rows into each other, and a tail of
+  `R$ 0,7x mi` values cannot be ordered or audited by the reader. If the table is
+  too wide, drop a column rather than shortening a number.
+- **Crescimento mensal is the seller's month-over-month sales growth** — the figure
+  the JoomPulse seller page shows. Name it that way rather than "trend", so it
+  cannot be confused with an older run-rate measure that is empty for most sellers.
+- **Medalha is a column, not only a chart colour.** The downloadable file is the
+  baseline the seller brings back next period, so it has to carry every field the
+  report and its panel use — a file that cannot reproduce the chart is not a
+  baseline.
+- **Say which figures are category-scoped and which are store-wide.** Sales,
+  revenue, brands and product counts are for this category; completed sales,
+  cancellation rate, growth, international shipping and the listing-type counts are
+  the whole store. That is why the listing-type counts do not add up to the category
+  product count, and it needs saying every time, not just when it looks odd.
+- **If the table is too wide for the surface, drop columns from the right** —
+  listing types first, then international shipping, then brands — and say which were
+  dropped; the downloadable file always keeps all of them. Never move sellers into a
+  numbered list, a paragraph, or a trailing "and below them, X, Y, Z" sentence, and
+  never carry only the leaders in the table with the rest in prose. The user saves this
+  table and pastes it back next period, and a list cannot be compared row against row.
+  **If the sellers you ranked are not all rows of one markdown table, you have not
+  produced the leaderboard.**
 
 **Comparison (only when a previous leaderboard is supplied):** the same table plus
 a **Variação** column, and a **Destaques** block (maiores altas / maiores quedas).
@@ -148,8 +209,15 @@ The panel contains:
   light background). Include a small legend mapping color to medal. When one seller
   dwarfs the rest, you may show that leader as a separate highlighted figure and
   chart the remaining leaders so the medal colors stay readable.
-- **A small "registered versus with sales" comparison** for sellers and for
-  products, to show how much of the supply actually converts.
+- **A small "registered versus with sales" comparison** for sellers — how many of
+  the category's sellers actually sell. **Do not chart the same comparison for
+  products, and never describe the product gap as stock sitting idle or failing to
+  convert.** On a catalog product only the seller holding the buy-box shows sales,
+  so every other seller of that product reads zero: a shop with thousands of
+  listings and a third of them "with sales" is mostly showing buy-box position, not
+  dead inventory. If the product split appears at all, label it buy-box coverage
+  and say what it is not — the panel renders every time now, so an unlabelled
+  version of this chart would mislead on every run rather than occasionally.
 
 Presentation rules: use the medal palette consistently; render a chart only when
 the data supports it; the movement/Variação column uses a word header, never a bare
@@ -165,7 +233,17 @@ The seller should never see a system or stack error — only a friendly next ste
   plainly and fall back to the leaderboard only; do not force a misaligned comparison.
 - **Small sample:** if only a few sellers come back, say so rather than implying it
   is the whole category.
-- **Market data temporarily unavailable:** retry once quietly; if it is still
-  down, say market data is temporarily unavailable and to try again. Never paste
-  internal error text, HTTP codes, or field names to the seller.
+- **Missing values.** Show `—` for any figure that is unavailable. Never print `0`
+  or `0,00%` for something unknown: a cancellation rate of `0,00%` on a seller with
+  no completed sales reads as a perfect record when nothing was measured at all.
+- **Growth on a small base.** A percentage computed on a handful of real sales is
+  noise, not a trend. Show it, but say so beside it, and never lead the risers list
+  with one.
+- **Market data temporarily unavailable:** retry once after a short pause rather
+  than immediately; if it still fails, say the service is busy and to try again in a
+  few minutes. Never paste internal error text, HTTP codes, or field names to the
+  seller. Name the downloadable file so the seller can find it, but never expose an
+  internal working path — a temporary or scratch directory is not a save location.
+- **An empty result is not a failure.** A category with no sellers to rank is an
+  answer; say that and offer a broader category. Never report it as an outage.
 - **Never silently limit coverage** — state the top cap you used.