zach-product-research

Prerequisites

This public version of the Skill is self-contained and does not depend on any private workspace files, internal reference libraries, or brand-specific protocols.

Before starting the analysis, prioritize reading the reference materials included with this Skill:

• references/payload_schema_v2.md — v2 data package structure and required fields
• references/payload_schema.md — v1 compatible format
• references/html_report_spec.md — HTML condensed report structure requirements
• references/analysis_patterns.md — Analysis modes and insight writing templates

If you already have your own market research materials, they can be used as supplementary background; however, the execution, delivery, and validation of this Skill do not depend on external private materials.

Product Research Analyzer (Product Research - Sorftime MCP)

Positioning

Based on Sorftime MCP product selection analysis, helping you discover high-potential market opportunities in the shortest time and with the lowest risk, provided there is profit.

Data source: All obtained through Sorftime MCP tools, no fabrication, no estimation.

Downstream output: Product selection report (MD + HTML condensed + Dashboard + Excel) → subsequent steps of the new product listing workflow:zach-competitor-deep-dive(Listing-level competitor breakdown) → zach-pricing-strategy(pricing calculation) → …

Note: This Skill has absorbed the Go/No-Go decision framework and entry barrier assessment capabilities of the original zach-market-intelligence , as well as the Dashboard visualization capabilities of zach-report-dashboard-renderer . Both have been marked as deprecated.

Script Directory

• scripts/render_deliverables.py
  • Purpose: render the unified JSON data package as md + html精简 + dashboard看板 + xlsx + json, and perform delivery validation
  • v2 mode(recommended): payload contains schema_version: “2.0” + chapters, the renderer generates tables from structured data + inserts LLM insight paragraphs
  • v1 compatible mode: payload contains report_markdown / report_html, write directly (legacy process)
  • Command:
    • python skills/zach-product-research/scripts/render_deliverables.py generate --input <payload.json>
    • python skills/zach-product-research/scripts/render_deliverables.py validate --input <payload.json>
    • python skills/zach-product-research/scripts/render_deliverables.py all --input <payload.json>
  • When to use: Step 5 delivery stage; it is forbidden to manually supplement only a single file and then directly end the task
• scripts/parse_top100_dimensions.py
  • Purpose: parse Top100 title dimensions according to the rule file, output top100_parsed.json and uncertain_products.json
• scripts/cross_analysis.py
  • Purpose: generate cross matrices and opportunity gaps based on the parsed product JSON

References

• references/payload_schema_v2.md
  • Purpose: v2 payload structure definition (10 chapters + excel_sheets), for when preparing render_deliverables.py input data package
• references/payload_schema.md
  • Purpose: v1 payload structure definition (backward compatibility reference)
• references/html_report_spec.md
  • Purpose: HTML condensed report block definition reference
• references/analysis_patterns.md
  • Purpose: templates and examples for the four analysis modes, must be referenced when writing the report (use at least 3)

Assets

• assets/html_report_template.html
  • Purpose: HTML condensed report template (used by v1, v2 is rendered built-in by render_deliverables.py)
• assets/dashboard_template.html
  • Purpose: Dashboard visualization template (migrated from zach-report-dashboard-renderer), v2 automatically injects data via render_deliverables.py

Agents

• agents/data-pipeline.md
  • Purpose: responsible for Sorftime raw data → intermediate JSON / Excel Sheet data
• agents/insight-writer.md(new in v2, replaces report-writer.md)
  • Purpose: Responsible for writing analytical insight paragraphs within the fixed 10-chapter structure (do not write table formats/HTML)

Evals

• evals/evals.json
  • Purpose: Minimal self-test suite
• evals/files/sample_payload_minimal.json
  • Purpose: Minimal sample for the delivery pipeline

---

Core Principles

1. Weight Priority: The greater the weight, the more free traffic
2. Profit Monitoring: Profit covers advertising costs and maintains a healthy ROI
3. Battlefield First: Choose the right market first, then refine the product
4. Data-Driven: Use quantifiable metrics to judge the market and competitors
5. Differentiated Competition: Improve conversion through optimized design, selling points, and packaging

---

Hard Rules (⛔ Cannot Be Omitted)

The following rules apply to all scenarios, regardless of model capability or whether the user explicitly requests them:

1. ⛔ Category Top100 details must output the complete 100 entries; do not abbreviate them as "representative products"
2. ⛔ Competitor negative review analysis must include a "Competitor Selection Logic Table" (ASIN + selection reason + competitor type + coverage dimensions), with a total of 6-10 competitors, covering scale benchmarks/feature differences/price bands/pain points
3. ⛔ Keyword analysis must cover a comparison of at least 3 dimensions (e.g., category broad terms vs attribute terms vs specification/scenario terms)
4. ⛔ Every data table/statistical conclusion that appears in the MD report must have a corresponding Sheet in Excel
5. ⛔ After each Step is completed, perform a data integrity check before proceeding to the next step
6. ⛔ Before output, execute the Step 5 delivery self-check list
7. ⛔ Targeted category analysis (Scenario 4) must execute Step 1.5 Product Attribute Tagging
8. ⛔ Negative review pain points must be categorized by attribute dimension (not only by product)

Hard Rules for Report Writing (⛔ Cannot Be Omitted)

The following rules ensure that each report reaches the level of analytical depth of "Power Bank v2," rather than being a mere pile of data:

1. ⛔ Pure data presentation is prohibited: Each data table must be immediately followed by a "Key Insights" paragraph (2-4 bullets), explaining the business implications of the data; do not just present tables without interpretation
2. ⛔ Must have an Executive Summary: The report must begin with 3-5 core conclusions, each structured as:数据点 → 含义 → 行动建议
3. ⛔ Cross-analysis must explain the reasons: Each "blank"/"thin supply" label must be accompanied by a cause analysis (technical limitation? demand does not exist? overlooked by the market? supply chain difficulty?), and must not merely label the status
4. ⛔ Negative review pain points must map to brand opportunities: The negative review pain points of each dimension must complete the mapping of 痛点 → 品牌能力 → 产品方案 ; do not merely list pain points without providing solutions
5. ⛔ Strategic recommendations must include a product matrix: At minimum, provide the complete specifications of Tier 1 products (dimension specification table + decision rationale + target pricing + differentiation proposition + benchmark competitors + estimated monthly sales potential); "to be confirmed" placeholders are absolutely not allowed
6. ⛔ Supply-demand gaps must be prioritized: Rank by three-dimensional assessment (market size 40% + technical feasibility 30% + brand fit 30%); do not list them flatly
7. ⛔ Analytical modes must be used: Each report must use at least 3 of the following 4 analytical modes (see references/analysis_patterns.md）：

Mode	Core Logic	Minimum Usage Count
Data→Blank→Opportunity	Discover supply gaps from distribution data and evaluate opportunity value	1 time
Pain point → advantage mapping	Map negative-review pain points to brand capabilities and product solutions	1 time
Cross-dimension → structural gap	Discover structural market gaps through multi-dimensional intersection	1 time
Multi-dimensional evaluation → priority matrix	Rank priorities through multi-factor weighted evaluation	1 time

---

Sorftime MCP tool list

When performing product selection analysis, call the following Sorftime MCP tools (⛔ = required, 📋 = as needed):

Category	Tool	Purpose	Priority
Category	category_search_from_product_name	Search related subcategories by product name	⛔ Required
	category_search_from_top_node	Search subcategories by major category	📋 As needed
	search_categories_broadly	Broad multi-dimensional category search	📋 As needed
	category_name_search	Query NodeId by category name	📋 As needed
	category_report	Category real-time Top100 report	⛔ Required
	category_report_from_history	Category historical Top100 report	📋 As needed
	category_trend	Category trend data (⛔ NewProductSalesAmountShare required)	⛔ Required (Step 1.7)
	category_keywords	Category core keywords	📋 As needed
Keyword	keyword_search_results	Organic-position products in keyword search results	📋 As needed
	keyword_detail	Keyword details	⛔ Required
	keyword_extends	Keyword extended terms	📋 As needed
	keyword_trend	Keyword historical trends	📋 As needed
Product	product_search	Product search	📋 As needed
	product_detail	Product details (attribute annotation supplementary verification)	⛔ Required (Step 1.5)
	product_trend	Product trends	📋 As needed
	product_reviews	Product reviews	⛔ Required (Negative)
	product_traffic_terms	Reverse keyword lookup for products	📋 As needed
	product_variations	Product variations	📋 As needed
Product selection	potential_product	Potential product search	📋 As needed
	competitor_product_keywords	Competitor keyword exposure	📋 As needed
Supply chain	ali1688_similar_product	1688 similar products (procurement cost)	📋 As needed

⛔ Required tool explanation: Regardless of the scenario, these 6 tools must be called, and their output is the source of the report's core data. 📋 As-needed tools are called selectively according to the scenario and user needs.

---

Gotchas (most common pitfalls during execution)

1. The Skill exists locally, which does not mean it is loaded in the current session

   • If the repository already contains skills/zach-product-research/, but the current session still indicates the skill is unavailable, first check:
     • Whether the current IDE or Agent has reloaded the workspace configuration
     • Whether there is a historical alias (such as product-research) that is inconsistent with the official name
   • Important: Even if you fix the disk files, the skill list of the current session may not hot-reload; when necessary, explicitly prompt "the current session needs to be reopened / a new session needs to reload skills".

2. Sorftime MCP may have per-call authorization friction on desktop

   • Before large-scale concurrent calls, prioritize doing a "minimal closed loop": first get the category, keywords, and Top100 core data, then decide whether to dig deeper.
   • When batch supplementing calls, by default use <= 8 per batch, to avoid spreading too many tool calls at once and being interrupted midway by the user confirming them one by one.
   • If the environment allows network access, and the local machine ~/.cursor/mcp.json already has Sorftime configured, consider usinglocal direct-connect HTTP MCP as a non-interactive fallback;strictly prohibited to echo the real key。

3. Broad keywords often mix pools; clean the keyword pool before estimating the market

   • Do not by default treat the words given by the user directly as the "machine itself market".
   • Typical case:essential oil diffuser will mix in essential oil itself, humidifier, reed diffuser, and consumables ecosystem.
   • You must first use category_name_search / keyword_search_results / title samples to check and confirm whether the result pool is actually the same competitive unit, then make a market size judgment.

4. Do not directly hard-read large-volume Top100 data

   • By default, first go through title parsing, then supplement calls for unknown items product_detail。
   • If Top100 / reviews / details return very large results, first write intermediate files, then use scripts to extract fields; do not rely on manually reading large JSON.

5. Producing only Markdown does not count as complete

   • As long as the user wants a formal deliverable, you must run render_deliverables.py all, and simultaneously produce MD + HTML精简 + Dashboard + XLSX。
   • If the directory only contains .md, no matter how complete the analysis is written, it is consideredincomplete。

6. render_deliverables.py has strict validation thresholds

   • excel_sheets The first one must be 数据来源说明
   • If required Sheets are incomplete, validation will fail
   • The v2 payload must contain 10 chapters
   • Insufficient Markdown insight depth, missing Tier product matrix, and missing Go/No-Go scorecard will also be exposed during the validation stage

---

Execution flow

Step 0: Information collection (interactive)

After receiving the call, first confirm the following key information:

📋 选品分析 - 信息确认

1. 目标站点：[US/UK/DE/FR/IT/ES/CA/JP，默认US]
2. 选品场景：[新手入门/蓝海发现/季节性/品牌打造/定向品类分析]
3. 约束条件（可选）：
   - 价格区间：如 $10-40
   - 月销量：如 > 1000
   - 品类偏好：如 家居/电子/宠物
   - 预算：如 10万人民币
4. 产业带优势（可选）：如有特定供应链优势

If the user does not provide information: default to the "beginner entry" scenario, US site, price $10-40, no specific industrial belt.

Step 1: Discover opportunity markets

1.1 Category market scan

Call search_categories_broadly or category_search_from_product_name to filter categories meeting the following conditions:

• New product sales share > 15%
• Number of brands > 80 (fragmented market)
• Top3 sales share < 40% (low monopoly)
• Average price $10-40 (beginner-friendly)
• Moderate monthly sales scale (depending on budget)

1.2 Keyword opportunity mining (⛔ must compare across multiple dimensions)

For candidate categories, call keyword_search_results + keyword_detail：

• Search volume > 10000/month
• Organic position monthly sales > 50000
• Number of competitor reviews on the first page < 500 (threshold can be caught up to)
• CPC price (advertising cost) acceptable

⛔ Multi-dimensional keyword comparison table: Keyword analysis must cover at least 3 levels/dimensions, and must not analyze only the single dimension mentioned by the user.

Dimension examples (adjust according to category):

Dimension	Example keywords	Description
Category head term	power bank, portable charger	Largest traffic entry point
Attribute term	fast charging power bank, wireless power bank	Function/feature segmentation
Specification/parameter term	65W power bank, 20000mAh portable charger	Specific specification parameters
Scenario term	laptop portable charger, camping power bank	Usage scenario segmentation

Keywords for each dimension must call keyword_detail to obtain the following data and output a comparison table:

Keyword	Dimension	Monthly search volume	CPC	Number of natural-ranking products	Average number of reviews on the first page	Data source

Checkpoint: After confirming that keywords for at least 3 dimensions all have keyword_detail data, proceed to Step 1.3.

1.3 Preliminary screening of potential products

Call potential_product + product_search：

• Monthly sales > 1000
• Price $10-30
• Rating > 4.0
• Time on market < 6 months (new products have opportunities)

Step 1.4: Analysis dimension self-discovery (executed when the user does not specify dimensions)

When the user is unfamiliar with the target category and cannot specify analysis dimensions, the model needs to autonomously discover the key differentiation dimensions of that category. This step is executed before Step 1.5 (attribute tagging), and its output is the dimension definition for attribute tagging.

Trigger conditions: The user has not explicitly specified analysis dimensions, or has specified ≤ 2 dimensions.

Execution method(four parallel paths, results synthesized):

Path 1: Clustering high-frequency words in Top100 titles

• Perform word frequency statistics on the 100 product titles returned by category_report Perform word frequency statistics on the 100 returned product titles
• Filter out generic words (category-generic words such as brand, portable, charger)
• Keep attribute words with an occurrence frequency ≥ 10% as candidate dimensions
• Example output:slim appears 23 times → candidate dimension "appearance form"

Path 2: Keyword extension term analysis

• Call keyword_extendsfor the category core term to analyze what modifiers consumers use when searching
• High-search-volume modifiers = differentiation dimensions consumers care about
• Example:keyword_extends("power bank") → "65W power bank", "slim power bank" → candidate dimensions "power" and "form"

Path 3:product_detail attribute field Key extraction

• Call product_detail
• for the Top5 best-selling products. Extract key names(not values) from the returned "attributes" field as structured dimension candidates
• Example: attributes include Battery Capacity, Connector Type → candidate dimensions "capacity" and "interface type"

Path 4: WebSearch category review articles (optional)

• Search "[category] buying guide" or "[category] how to choose"
• Extract the key parameters for consumer decision-making from review articles
• Example: Wirecutter reviews focus on "capacity, charging speed, size, ports" → candidate dimensions confirmed

Output: A list of candidate dimensions (5-8), each dimension includes:

• Dimension name
• Discovery source (title word frequency/extension words/attribute Key/review articles)
• Candidate category values (e.g., power → ≤15W / 15-22.5W / 30W / 45W / 65W / 100W+)

⛔ Must have the user confirm: After outputting candidate dimensions, ask the user to confirm/delete/add, then proceed to Step 1.5. The user may have category knowledge to supplement dimensions that the model cannot discover.

Checkpoint: After confirming at least 3 analysis dimensions, proceed to Step 1.5.

---

Step 1.5: Top100 product attribute annotation (P0 - required for multi-dimensional analysis)

This step upgrades the Top100 basic data returned by category_report into structured multi-dimensional attribute data, and is the foundation for subsequent cross-analysis and differentiation recommendations.

Input：Step 2.1 category_report : the Top100 product list returned by Step 2.1 category_report (this step can be executed immediately after obtaining the Top100, in parallel with Step 1)

⛔ Basic fields that must be extracted(common to all categories,category_report directly returned):

Field	Source	Purpose
上线日期	category_report original field	Step 1.7 new product analysis
上线天数	category_report original field	Step 1.7 new product analysis

These two fields are already present in the data returned by category_report and must be extracted together during parsing; do not discard them.

Annotation dimensions(customized by category; the following is a power bank example; other categories need custom dimensions based on category characteristics):

Dimension	Parsing method	Example rules (power bank)
Power	Regex (\d+\.?\d*)\s*[Ww] + V/A calculation (V×A=W)	22.5W, 65W, 5V/3A=15W
Capacity	Regex (\d[\d,]*)\s*[Mm][Aa][Hh] (ignore case, handle commas)	10000mAh, 20,000 mAh
Cable	Keywords "built-in cable", "built in", "with cable", "integrated cable"	Built-in cable/External cable/None
Digital display	Keywords "LED display", "digital display", "LCD", "battery indicator"	Yes/No
Magnetic/wireless charging	Keywords "MagSafe", "magnetic", "Qi2", "wireless charging", "Qi"	MagSafe/Qi2/Qi/None
Form factor	Keywords "slim", "thin", "mini", "compact", "small", "lightweight"	slim/mini/standard

Execution method(three stages):

1. Title regex + keyword automatic annotation(coverage about 70-80%)

   • Iterate through the Top100 product titles and extract each dimension according to the rules in the table above
   • Annotate each product with confidence: high (explicit match) / low (ambiguous or missing)

2. ⛔ product_detail supplementary verification(for about 20-30% of products with low confidence)

   • For products whose titles cannot confirm the attributes, call product_detail to get bullet points / product description
   • Extract missing attribute information from the description
   • Call up to 8 in parallel per batch to improve efficiency

3. Manual override record

   • Record all manually corrected products and the reasons for correction
   • Facilitates subsequent review and accumulation of experience

⚠️ Title parsing notes(See the "Title Parsing Experience Library" section at the end of the document)

Output：

File	Content
top100_parsed.json	Add N attribute columns per product + confidence annotation
uncertain_products.json	Required product_detail list of products to be verified and verification results

Checkpoint: Confirm that attribute annotation has been completed for all 100 products (some dimensions are allowed to be "unknown", but skipping the annotation step is not allowed), then proceed to the next step.

Step 1.6: Multi-dimensional cross-analysis (P1 - execute after attribute annotation is completed)

Based on the structured attribute data from Step 1.5, generate a cross-analysis matrix to identify supply-demand gaps and blank spots in market opportunities.

Applicable conditions：

• Products have completed multi-dimensional attribute annotation (Step 1.5)
• Need to find supply-demand gaps (dimension combinations where search demand exists but supply is low)
• Need to discover blank spots in product portfolio opportunities

Standard cross table：

Generate a cross matrix for all meaningful dimension pairs:

Cross dimensions	Analysis metrics	Description
Dimension A x Dimension B	Number of products	How many products are under this combination
Dimension A x Dimension B	Total monthly sales volume	Market demand for this combination
Dimension A x Dimension B	Total monthly sales revenue	Market value of this combination
Dimension A x Dimension B	Average price	Price level of this combination

Examples (power banks): power x capacity, power x magnetic attachment, capacity x cable, power x appearance form, etc.

Automatically identify supply-demand gaps：

• Blank spots: Dimension combinations with product count = 0 → potential blue ocean opportunities (need to verify whether demand truly exists)
• Thin supply: Combinations with product count ≤ 2 → low-competition opportunities (few on sale, low competition)
• High demand low supply: Combinations with high monthly sales but few products → optimal opportunity

Brand concentration analysis：

• Sales share of the Top3 brands in each major dimension combination
• Identify combinations with severe brand monopoly (avoid) vs combinations with dispersed brands (opportunity)

Output：

File	Content
cross_analysis.json	All cross-analysis matrix data
List of opportunity blank spots	Include in the "Market Opportunities" chapter of the final report

⛔ Cross-analysis output format requirements：

The output for each pair of cross dimensions must not be only a table; it must include the following structure:

1. Cross matrix table(Number of products / Monthly sales volume / Monthly sales revenue / Average price)
2. Key findings paragraph(2-4 bullets), must answer:
   • Which combinations are the market mainstays? (High supply + High demand)
   • Which combinations have supply-demand gaps? (High demand + Low supply)
   • Which combinations are false opportunities? (Low supply + low demand, effectively no demand)
3. Blank/thin supply label definitions and analysis requirements：

Label	Definition	Required additional analysis
Blank	Product count = 0	Cause analysis (technically infeasible? demand nonexistent? overlooked?) + demand validation methods
Thin supply	Product count ≤ 2	How are existing products performing? (sales/reviews) + difficulty of competitive entry
High demand, low supply	Monthly sales Top 30% but product count Bottom 30%	Why is supply low? + entry feasibility assessment

Checkpoint: Confirm that at least 3 dimension-pair combinations have completed cross-analysis, and each pair has a "Key Findings" paragraph (not just a table); the blank spot/thin supply list has been generated with cause analysis attached, then proceed to Step 1.7.

Step 1.7: New product analysis (⛔ mandatory)

Based on the 上线日期 field already extracted in Step 1.5, analyze the proportion, performance, and trends of new products in the Top 100 to judge how friendly the category is to new products. This is a key input for product selection decisions—a category with a high proportion of new products means newcomers have opportunities; otherwise, the barrier is high.

Data source：

• category_report returned by 上线日期/上线天数 field (already extracted in Step 1.5, zero additional API cost)
• category_trend(trendIndex=NewProductSalesAmountShare) → 1 API call

Execution steps：

1. Listing time bucket statistics

Bucket the Top 100 by listing time, and calculate the product count and sales share for each bucket:

Time period	Product count	Monthly sales	Sales share
≤3 months
3-6 months
6-12 months
1-2 years
2-3 years
3 years+

2. Details table of new products within six months

List all products listed ≤6 months ago, in descending order of monthly sales:

| ASIN | Brand | Price | Monthly sales | Launch date | Days | Review count | [each attribute dimension] |

Focus on:

• Which brands are among the new products? (all big brands vs. white-label breakouts)
• Have new products entered the Top 50? (can they break into the top tier)
• What attribute combinations do the new products have? (validation of market supply direction)

3. Trend of new product sales share

Call category_trend（trendIndex=NewProductSalesAmountShare) to obtain the monthly trend of new product sales share over the past 2 years:

• Trend rising → category active, friendly to new products
• Trend stable at a low level (<5%) → category mature, dominated by old products, new products struggle to break through
• Trend declining → category solidified, new product entry not recommended

4. New product friendliness judgment

Based on the above data, give a new product friendliness rating for the category:

Metric	Friendly (green light)	Moderate (yellow light)	Unfriendly (red light)
Number of new products within six months in Top 100	≥10%	5-10%	<5%
Sales share of new products within six months	≥10%	5-10%	<5%
Number of new products entering Top 50	≥3	1-2	0
Are there non-top brands among new products?	Yes, white-label/new brands	Only tier-2/3 brands	All top brands
Trend of new product sales share	Rising	Stable	Declining

Output: Include in the report's "Market Overview" section, including the listing time distribution table, new product details, trend chart data, and new product friendliness rating.

Checkpoint: Complete the new product analysis and provide the new product friendliness rating before proceeding to Step 2.

Step 2: Validate the competitive landscape

2.1 Category deep dive

Call category_report to get the Top 100, and analyze:

• Brand concentration (brand monopoly coefficient)
• Seller type distribution (FBA/FBM/Amazon self-operated ratio)
• New product ratio (share of products listed within six months)

Checkpoint: Confirm that the number of products returned by category_report = 100 (⛔ Hard Rule No. 1). If fewer, call again or explain why.

2.2 Detailed competitor analysis (⛔ Negative review analysis must include selection logic)

For key products, call product_detail + product_reviews：

• Sales rank, price trend, rating and review count
• Positive review keywords (what users value)
• Negative review pain points (improvement opportunities)

⛔ Competitor selection logic table: Before conducting the negative review analysis, you must first output the competitor selection logic table, explaining why these competitors were chosen:

ASIN	Brand	Reason for selection	Competitor type	Coverage dimension
B0XXXXXXXX	BrandA	Category sales Top 3	Scale benchmark	Price band - mid
B0YYYYYYYY	BrandB	No. 1 in sales in the high-power segment	Functional differentiation representative	Power - high
B0ZZZZZZZZ	BrandC	Highest negative review rate (below 4.0)	Pain point reference	Dense pain points
B0WWWWWWWW	BrandD	Entry-level model in the magnetic category	Functional differentiation representative	Magnetic - entry-level
B0VVVVVVVV	BrandE	Representative of the high-end price band	Price band coverage	Price band - high
B0UUUUUUUU	BrandF	Low-price volume representative	Price band coverage	Price band - low

⛔ Competitor selection must meet the following coverage requirements：

Coverage dimension	Requirement	Description
Scale benchmark	At least 1-2	Category Top 5 sales products, representing the market standard
Functional differentiation representative	At least 1 for each major functional dimension	Such as: high-power representative, magnetic representative, built-in cable representative
Price band coverage	At least 1 each for high/mid/low	Ensure the analysis covers the full price range
Pain point reference	At least 1-2	Products with a high negative review rate or low star rating, to uncover improvement opportunities

• Total: 6-10 competitors
• For each major attribute dimension(from Step 1.5 annotation) at least 1 representative product

Selection Recommendations: Select 1-2 representatives per sub-segment (e.g., price band, power range, use scenario), covering leading competitors + pain-point competitors.

Checkpoint: After the competitor selection logic table is complete, call product_reviews(reviewType=Negative) one by one to perform negative review analysis. Maximum 8 parallel calls per batch.

⛔ Negative Review Analysis Classified by Dimension: Negative review pain points must be categorized by attribute dimension (e.g., power-related, cable-related, digital display-related, capacity-related, magnetic attachment-related, appearance/form-related, general quality issues), not merely by product. Only then can they directly map to product design decisions.

2.3 Keyword Competition Analysis

Call competitor_product_keywords + product_traffic_terms：

• Core keyword rankings
• Number and distribution of traffic keywords
• Organic traffic vs. ad traffic ratio

2.4 Entry Barrier Assessment (⛔ Mandatory, originally market-intelligence Step 4)

Applicable scenarios: Must be output for all formal delivery versions. This section is used to clearly explain the risks of "whether it can be done," avoiding presenting only opportunities without discussing the threshold.

Evaluate the following barrier dimensions, giving each dimension a level (Low/Medium/High):

Barrier Type	Evaluation Content	Data Source
Review Barrier	How many Reviews are needed to reach the first page	category_report Top100 review count distribution
Capital Barrier	First batch inventory + advertising + first-leg shipping	ali1688_similar_product + estimation
Technical Barrier	Whether certification/patent/mold is needed	WebSearch + category knowledge
Compliance Barrier	FDA/UL/CE/FCC and other certifications	WebSearch (see site compliance table below)
Supply Chain Barrier	Supplier threshold/MOQ	ali1688_similar_product
Brand Barrier	Whether brand story/loyalty is needed	Competitive landscape analysis results

Site Compliance Quick Reference：

Site	Common Certification Requirements
US	FDA (food/cosmetics), UL (electronics), FCC (wireless), CPSC (children's products), EPA (pesticides)
UK	UKCA、WEEE
DE	CE, WEEE, EPR, VerpackG (packaging law)
FR	CE, EPR, Triman logo
IT/ES	CE、EPR

Output: Barrier summary table (type + level + estimated cost + estimated time) + total estimated startup investment

Step 3: Input-Output Calculation

Financial Formula：

毛利 = 售价 - 采购成本 - FBA费用 - 物流成本
净利润 = 毛利 - 广告成本 - 退货损耗 - 平台佣金(约15%)
毛利率 = 净利润 / 售价 * 100%

预估CPC：从 keyword_detail 获取
目标ACOS = 毛利率 * 50%（保守）
净利率 = 净利润 / 售价 * 100%

Logistics Cost Reference：

• Price $10-20: Keep logistics cost within 15% of selling price
• Price $20-40: Can bear higher logistics cost

Procurement Cost: Can call ali1688_similar_product to obtain 1688 supply reference prices.

Step 3.5: Go/No-Go Comprehensive Scoring (⛔ Mandatory, originally market-intelligence Step 6)

Applicable scenarios: Must be output for all formal delivery versions. Even if the user is already inclined to enter, the "entry conditions, prerequisite risks, and final judgment" must be explicitly written out.

Scoring System (Weighted Calculation)：

Dimension	Weight	Score (1-10)	Data Source
Market Size	20%	X	Step 1.1 category_report
Competitive Landscape	25%	X	Step 2.1 Brand Concentration/New Product Share
Demand Clarity	15%	X	Step 1.2 Keywords + Step 1.6 Cross-Analysis
Entry Barriers (Reverse)	20%	X	Step 2.4 Barrier Assessment
Profitability	20%	X	Step 3 Input-Output Calculation

Decision Matrix：

Weighted Total Score	Decision	Recommendation
7.5-10	GO	Strongly recommend entering, prioritize advancement
6.0-7.4	CONDITIONAL GO	Conditional entry, key risks must be resolved
4.0-5.9	HOLD	Hold, need more data validation or wait for the right timing
0-3.9	NO-GO	Not recommended to enter, risks outweigh opportunities

Output: Scorecard + Decision Recommendation + Top3 Opportunities + Top3 Risks + Mitigation Plans

Note: If the decision is NO-GO, the process terminates and does not proceed to Step 4.

Step 4: Differentiation Recommendations and Product Matrix (⛔ Must be specific down to specifications)

This step is the core value output of the report—transforming data analysis into an executable product strategy. "To be confirmed" placeholders or merely listing directions without specifications are strictly prohibited.

4.1 VOC Pain Point Dimension Mapping

Based on the negative review analysis in Step 2.2 (already categorized by dimension), perform the four-element mapping for each dimension:

Element	Description	Example (Power Bank - Power Dimension)
Pain Point Description	The most frequent consumer dissatisfaction under this dimension	"Charging speed is slow; advertised fast charging is actually only 10W"
Data Support	Negative review frequency/share + competitors involved	23% of negative reviews mention slow charging, involving Brand A/B/C
Brand Opportunity	The brand's capability advantage in this dimension	The target brand has fast-charging or supply chain advantages and can deliver a true 65W
Product Solution	Specific product design direction	Standard 65W GaN + LED real-time power display to eliminate trust concerns

⛔ Every attribute dimension (from Step 1.5) must complete this mapping table; none may be omitted.

4.2 Opportunity Gap Prioritization

Summarize all gaps/thin supply/high-demand-low-supply opportunities identified in the Step 1.6 cross-analysis, and rank them by three-dimensional assessment:

Assessment Dimension	Weight	Scoring Criteria (1-5 points)
Market Size	40%	1=Monthly sales <$50K, 2=50-200K, 3=200-500K, 4=500K-1M, 5=>1M
Technical Feasibility	30%	1=Requires major R&D, 2=Requires new molds, 3=Improve existing solution, 4=Mature solution, 5=Can be covered by existing product line
Brand Fit	30%	1=Completely mismatched, 2=Requires new brand positioning, 3=Partially matched, 4=Highly matched, 5=Core strength area

Output Format：

Rank	Opportunity Description	Dimension Combination	Market Size (40%)	Technical Feasibility (30%)	Brand Fit (30%)	Weighted Total Score	Recommended Action
1	[Specific description]	[Dimension A×Dimension B]	X	X	X	X.X	[Specific Actions]

4.3 Product Matrix Planning

Based on the priority ranking, plan the specific product matrix. Complete at least Tier 1 (the highest-priority products to enter); Tier 2/3 depends on data sufficiency:

Tier Template(Each Tier must include all of the following fields):

### Tier [N]: [产品定位一句话]

**目标市场**：[对应的维度组合空白/机会]
**决策理由**：[为什么优先做这个——引用 4.2 的优先级排序数据]

| 维度 | 规格 | 决策依据 |
|------|------|----------|
| [维度1] | [具体规格值] | [为什么选这个值] |
| [维度2] | [具体规格值] | [为什么选这个值] |
| ... | ... | ... |

**目标定价**：$XX.XX（基于 Step 3 测算，毛利率 XX%）
**差异化主张**：[一句话核心卖点，区别于竞品的关键]
**对标竞品**：[ASIN] [品牌] [价格] — 我们的优势：[具体差异]
**预估月销潜力**：XX-XX 件/月（基于同维度组合现有产品表现推算）

⛔ Prohibited Items：

• Placeholder phrases such as "pending Zach's confirmation," "TBD," or "further research recommended" are not allowed
• Listing only a direction without specific specifications is not allowed (e.g., "recommend a high-capacity version" must be changed to "recommend 20000mAh")
• Not marking the benchmark competitor is not allowed (a specific ASIN must be provided)
• Not providing the target price is not allowed (it must be based on the Step 3 calculation)
• If the data is truly insufficient to support a certain Tier, clearly mark "Insufficient data: missing XX data; recommend supplementing XX before deciding," but do not use vague phrases such as "to be confirmed" to gloss over it

Step 5: Pre-delivery Self-check (⛔ Mandatory)

⛔ Hard Delivery Rules

1. ⛔ Step-by-step output is prohibited: Do not manually output the MD report first and then call render_deliverables.py; all deliverables must be generated at once by render_deliverables.py all Generate in one go
2. ⛔ unified_payload.json must include product-level details：
   • excel_sheets["类目销量Top100_明细"] must include 100 product records
   • excel_sheets["属性标注_Top100"] must include attribute annotation results
   • The data sources for the two Sheets are top100_raw.json and top100_parsed.json
3. ⛔ The competitor selection logic must include price and sales volume：competitor_selection_logic Each record must contain the price/monthly_sales/reviews fields (obtained from product_detail)

Before outputting the report and data files, check the following checklist item by item.Only after all items pass may you output, and any failed items must be corrected before output:

• Category Top100 details = 100 records? (Fewer than 100 indicates incomplete data retrieval; you need to call again category_report）
• Have the Top100 products completed attribute annotation? (Step 1.5, each product is annotated with at least the defined dimensions)
• Has the cross-analysis completed at least 3 dimension combinations? (Step 1.6, including a list of blank spots/thin supply)
• Do the keywords for each analysis dimension have keyword_detail data? (At least 3 dimensions)
• Is the competitor negative review analysis accompanied by a "Competitor Selection Logic Table"? (Including ASIN + selection reason + competitor type + covered dimensions)
• Does the competitor selection cover scale benchmarks, functional differentiation representatives, high/mid/low price bands, and pain point references? (6-10)
• Have the negative review pain points been categorized by attribute dimension? (Rather than only by product)
• Does each data table in the MD report have a corresponding Sheet in Excel?
• Is the number of data records in Excel >= the number of data records in the MD report? (Excel must not have fewer than MD)
• Are all data points labeled with the Sorftime MCP source tool name?
• Is the first key in the JSON "Data Source Description"?
• Does the Excel Sheet list include "Competitor Selection Logic" and "Keyword Comparison_Segmented"? (If there is corresponding analysis)
• Does Excel include the "Attribute Annotation_Top100" and "Cross Analysis" Sheets? (If Step 1.5/1.6 was executed)
• Has the new product analysis (Step 1.7) been completed? (Including new product count/share/time buckets + new product friendliness rating)
• Has the streamlined HTML report been generated? (⛔ Three-piece set: MD + Excel + HTML)
• If Step 2.4 entry barrier assessment was performed, is the barrier summary table complete? (6 categories of barriers + level + cost + time)
• If Step 3.5 Go/No-Go scoring was performed, are the 5-dimension scores + weighted total score + decision recommendation complete?
• Does the "Category Sales Top100_Details" Sheet contain ≥100 records?
• Is the attribute labeling in the "Attribute Labeling_Top100" Sheet complete?
• Does each row of the competitor selection logic table include price/monthly_sales/reviews?
• Call render_deliverables.py all Generate in one go (not step by step)?

Insight quality check (⛔ must all pass)：

• Is there an Executive Summary (≥ 4 core conclusions, each containing data points + implications + action recommendations)?
• After each dimension distribution table, is there a "Key Insights" paragraph (2-4 bullets)?
• For each pair of dimensions in the cross-analysis, is there a "Key Findings" paragraph (not just a table)?
• Do all "blank"/"thin supply" labels have an explanation of the reason (technology/demand/neglected/supply chain)?
• After negative reviews are categorized by dimension, does each dimension have a "brand opportunity" mapping (pain point→capability→solution)?
• Is there a product matrix (at least Tier 1 containing a complete specification table + pricing + differentiation + benchmark competitors)?
• Do the opportunity gaps have priority ranking (three-dimensional weighted evaluation)?
• Does the report use at least 3 analysis modes (see references/analysis_patterns.md）？

---

"6-in-1" hidden profit index standard

The hidden profit index (potential index) evaluates the following 6 items; the higher the score, the better:

Indicator	Ideal state
Ranking trend	Stable or rising
Sales trend	Stable or growing
Price trend	Stable or rising
Review threshold	Few reviews, easy to catch up (<500)
Advertising cost	Low CPC or high organic traffic
Listing time	New product within six months

potential_product Can be sorted by potential index, prioritizing high-scoring products.

---

"Good market" evaluation criteria

Dimension	Ideal indicator
Traffic monopoly	Monopoly coefficient < 30%
Fragmented brands	Number of brands > 80
Active new products	New product share > 30%, new product sales share > 15%
Review threshold	Average number of reviews < 500
Price range	$10-40
After-sales risk	Return rate < 10%

---

Product selection output template

Each recommended product must include the following structure:

## 【产品名称】

### 一、市场概况
- **所属类目**：[类目名称 + NodeId]
- **目标关键词**：[核心关键词]
- **月销量规模**：[市场规模]
- **平均价格**：[价格区间]
- **数据来源**：[Sorftime MCP 工具名]

### 二、"6合1"验证
- [ ] 排名趋势：[稳定/上升/下降]
- [ ] 销量趋势：[稳定/增长/下降]
- [ ] 价格趋势：[稳定/上涨/下跌]
- [ ] 评价门槛：评论数[XXX]，可追赶
- [ ] 广告成本：CPC $[XXX]
- [ ] 上架时间：[XXX]个月内

### 三、竞争分析
- **品牌垄断系数**：[XX%]
- **Top3销量占比**：[XX%]
- **新品活跃度**：[高/中/低]
- **主要竞品**：[竞品ASIN及特点]

### 四、财务测算（USD）
| 项目 | 金额 |
|------|------|
| 售价建议 | $XX.XX |
| 采购成本 | $X.XX |
| FBA费用 | $X.XX |
| 平台佣金(15%) | $X.XX |
| 物流成本 | $X.XX |
| 预估毛利 | $X.XX |
| 毛利率 | XX% |
| 预估CPC | $X.XX |
| 目标ACOS | XX% |
| 净利率 | XX% |

### 五、差异化建议
- **痛点改进**：[具体改进方向]
- **卖点提炼**：[差异化卖点]
- **定价策略**：[价格方案]

### 六、风险提示
- [ ] 季节性风险：[是/否]
- [ ] 认证要求：[是/否]
- [ ] 专利风险：[是/否]
- [ ] 供应链风险：[注意事项]

---

Common scenario strategies

Scenario 1: Beginner entry (budget <150,000)

• Price $10-20
• Light and small items (reduce FBA costs)
• Categories with no after-sales risk
• Categories with Chinese sellers accounting for >70%
• Recommended: kitchen storage, pet supplies, headscarves and face masks

Scenario 2: Blue ocean discovery (low competition)

• Filter low-monopoly categories (search_categories_broadly set top3Product_sales_share < 0.4）
• Focus on niche markets where new products have obvious sales
• Look for Top400 long-tail opportunities
• Validate keyword competition intensity (keyword_detail）

Scenario 3: Seasonal products

• Use keyword_trend to validate seasonality
• Stock up 2-3 months in advance
• Monitor search volume trends
• Assess off-season inventory risk

Scenario 4: Targeted category/product analysis (user has specified a category)

Applicable when the user has already determined the product/category to analyze (e.g., "analyze the US power bank market", "analyze the competitive landscape of a certain category"), which differs from the "discover unknown opportunities" of Scenarios 1-3.

Differences from discovery-type scenarios：

Step	Discovery-type (Scenarios 1-3)	Targeted-type (Scenario 4)
Step 1.1 Category scan	Broadly search candidate categories	Skip——The user has specified the category, directly use category_search_from_product_name to locate the NodeId
Step 1.2 Keywords	Filter high-potential keywords	⛔ Multi-dimensional comparison——Must cover category head terms, attribute terms, specification terms, and scenario terms (at least 3 dimensions)
Step 1.4 Dimension discovery	📋 As needed	⛔ Recommended——Required when the user has not specified dimensions; skip when the user has specified dimensions
Step 1.5 Attribute tagging	📋 As needed	⛔ Required——Targeted analysis requires multi-dimensional structured data, and attribute tagging is a core step
Step 1.6 Cross analysis	📋 As needed	⛔ Recommended——Discover blank spots in dimension combinations to directly guide product definition
Step 2.2 Competitor selection	Select by potential index	Select by segment——Select 1-2 representatives each by price band/function segment/usage scenario to cover the full market landscape
Step 2.4 Entry barriers	⛔ Required	⛔ Required——The formal delivery version must clearly define the six types of barriers and the prerequisites for launch
Step 3.5 Go/No-Go	⛔ Required	⛔ Required——The formal delivery version must provide quantitative conclusions, not just direction
Step 1.7 New product analysis	📋 As needed	⛔ Required——Targeted analysis needs to assess new product entry feasibility
Step 1.3 Potential products	Core step	📋 As needed——Users care more about the existing market landscape than new product opportunities

Execution key points：

• Enter Step 1.2 keyword analysis directly from the category/product name collected in Step 0
• Keyword dimension coverage must be comprehensive (⛔ Hard rule No. 3)
• ⛔ Step 1.5 attribute tagging + Step 1.6 cross analysis must be executed (the core value of targeted analysis)
• Competitor selection must include a selection logic table (⛔ Hard rule No. 2), covering volume benchmarks/functional differences/price bands/pain points
• Negative review analysis must be categorized by attribute dimension
• Category Top100 still requires a complete 100 entries (⛔ Hard rule No. 1)

---

Output specifications

1. Data source attribution: Every data point must be attributed to the Sorftime MCP tool name
2. Quantitative metrics first: Use specific numbers rather than vague descriptions
3. Complete logic chain: From market discovery → competitive validation → financial calculation → differentiation recommendations
4. Risk disclosure: Must include potential risks and mitigation plans
5. Actionability: Recommendations must be specific and implementable

---

Data integrity rules (must be followed)

• Never fabricate data: All data must come from Sorftime MCP call results and must not be fabricated
• Attribute data sources: Attribute each data point to its source tool (e.g., mcp_sorftime_product_search）
• Distinguish facts from speculation: Facts must be supported by data; speculation must be marked "⚠️ Speculation"
• Attribute data timeliness: Note the data acquisition time or applicable time range

---

product_detail Returned fields and credibility guide

Sorftime product_detail The returned fields come from different sources and vary greatly in credibility. When attributing attributes, use them according to credibility priority.

Field	Corresponding Amazon location	Credibility	Usage recommendation
Title	Front-end product title	High	Primary parsing source, visible to consumers, false claims will lead to complaints
Product description	Bullet points / A+ text	Medium-high	Supplementary verification, marketing copy but contains specific parameters
Attributes	Backend Item Specifics	Medium-low	Structured but sellers may fill in randomly, requires cross-validation
Outer packaging dimensions	Logistics attributes	High	Can infer the product's actual size and help determine its form
Price/sales/reviews/ranking	Front-end public data	High	Basic information, use directly
Main image URL	Product image link	—	Currently cannot OCR, for manual viewing only

Usage priority: Title > Product description (bullet points) > Attribute fields (backend)

Common issues with attribute fields：

• Special Feature: Sellers often stuff irrelevant keywords,cannot be used as a basis for attribute determination
• Battery Capacity: Usually accurate (Amazon has format requirements), can be used directly
• Connector Type: Format is inconsistent (some write "USB-C", some write "Output: USB-C2+USB-A1"), requires parsing
• Color / Style: Usually accurate, can be used directly
• Empty fields：特征 Fields are often empty {}, do not rely on them

---

Intermediate data persistence rules

A multi-dimensional analysis process usually takes 2-3 hours or even spans sessions. To prevent data loss caused by context compression or session interruption, intermediate results must be persisted at key nodes.

⛔ Persistence checkpoints：

After completing the step	Files that must be saved	Description
Step 1.1 category_report	top100_raw.json	Raw Top100 data, the basis for all subsequent analysis
Step 1.4 Dimension auto-discovery	Record in session or append to report	User-confirmed dimension list
Step 1.5 Attribute tagging	top100_parsed.json + uncertain_products.json	Tagged data + to-be-verified list
Step 1.6 Cross analysis	cross_analysis.json	Cross matrix + blank spots
Step 2.2 VOC analysis	voc_analysis.json	Competitor selection logic + negative review classification

Principles：

• After each Step is completed, write the results to a file before proceeding to the next step
• If the session is interrupted, you can resume from the last saved file next time, avoiding re-calling the API
• JSON file naming is consistent with the standard output directory (see "Standard Output Directory Structure")

---

Sorftime return data processing rules (⛔ must use Python scripts)

The amount of data returned by Sorftime MCP is usually large (Top100 about 50KB+). Reading it directly with the Read tool will exceed the token limit and cause failure. All large Sorftime data returnsmust always be parsed with Python scripts, do not attempt to read directly with the Read tool.

Which tool returns require Python script processing

Tool	Return size	Processing method
category_report	~50KB (100 products)	⛔ Must use Python script parsing
product_detail(batch)	Each ~2-5KB, total size is large when batch ≥5	⛔ Must use Python script parsing
keyword_detail	Each ~0.5KB	Can be read directly for single calls, use scripts for batch
product_reviews	~5-20KB (by product)	Recommended to use Python script parsing
Other single calls	<5KB	Can be read directly

category_report data structure and parsing template

Sorftime category_report The structure of the returned datais not standard JSON, but is wrapped in list[0]['text'] , with a line of instruction text in front. It must be parsed in the following way:

import json

# raw_data 是 category_report 的返回值（保存为文件后读取）
with open('top100_raw.json', 'r') as f:
    raw = json.load(f)

# 结构：list[0]['text'] 包含 JSON，前面有指令前缀
text_content = raw[0]['text']
json_start = text_content.index('{')  # 找到第一个 { 的位置
data = json.loads(text_content[json_start:])

# data 现在是标准 dict，包含 Top100 产品列表
products = data.get('products', [])  # 具体 key 视返回格式而定

⛔ Do not：

• Do not use the Read tool to directly read the return file of category_report (it will exceed the token limit)
• Do not assume the return is standard JSON (it has an instruction prefix)

product_detail batch call rules

Rule	Description
At most 8parallel calls per batch	More than 8 may trigger rate limiting
Parse return results with Python scripts	Merge and process batch results, extract the required fields
Parse the title first, then make supplementary calls for "unknown" items	Title coverage is about 70-80%, only call product_detail for missing items, saving API calls

Standard two-step process(Step 1.5 refinement):

Step 1: 标题正则解析 100 个产品 → 标注已知/未知
Step 2: 对"未知"产品批量调 product_detail（每批 ≤8 并行）→ 从描述/属性中提取缺失值

This saves about 70-80% of API calls compared with calling product_detail for all 100 products.

product_reviews processing recommendations

• The amount of negative review data for each competitor is about 5-20KB
• Can be called in parallel batches: Consistent with product_detail , at most 8 ASINs per batch called in parallel, then merged and parsed, to reduce total time
• After batch-fetching negative reviews of 6-10 competitors, use a Python script to categorize them by dimension
• Save the categorization results as voc_analysis.json

---

Title Parsing Experience Library (P1 - Continuously accumulated by category)

This section records common pitfalls and empirical rules in title regex parsing, for reference when executing Step 1.5, to avoid repeating mistakes. Accumulate by category; after researching a new category, new experience entries should be added.

Common Pitfalls

Pitfall Type	Example	Misinterpretation	Correct Handling
Similar word confusion	"Lighting Input"	Lightning cable	This is an input port description, not a built-in Lightning cable
V/A power estimation	"5V/3A"	Power unknown	V x A = W, i.e. 5V/3A = 15W, 5V/2.4A = 12W
PD power inference unreliable	"PD Fast Charging"	equals 20W	PD could be any of 15W/18W/20W/30W, needs product_detail confirmation
"Fast Charging" meaning ambiguous	"Fast Charging Power Bank"	high-power fast charging	Actually could be any power from 12W-20W, needs product_detail confirmation
Capacity formats vary	"10000mah", "10,000 mAh"	parsing failed	Regex must ignore case [Mm][Aa][Hh], handle commas \d[\d,]*
Title marketing exaggeration	"Super Fast", "Ultra Quick"	high power	Marketing terms have no standard meaning and cannot be used as attribute values
Multi-function combined description	"3-in-1 Charger Cable"	three cables	Could be a single 3-in-1 cable, needs verification

Category-specific experience: Portable Charger / Power Bank

Dimension	Parsing Key Points	Regex/Rules
Power	Prioritize matching explicit W values; when no W value, estimate using V*A; if only "PD"/"Fast Charging" is present, mark as "to be confirmed"	(\d+\.?\d*)\s*[Ww] first;(\d+\.?\d*)\s*[Vv]\s*/?\s*(\d+\.?\d*)\s*[Aa] second
Capacity	Ignore case, handle comma separators	(\d[\d,]*)\s*[Mm][Aa][Hh]
Cable	Distinguish "built-in cable" from "input port"; "Lighting Input" is not a built-in cable	Keyword matching + exclude "input"/"port" suffixes
Magnetic	MagSafe/Qi2 belong to magnetic wireless charging; regular Qi/wireless belong to wireless charging but not magnetic	Layered labeling: MagSafe > Qi2 > Qi > none
Digital display	"LED" appearing alone may refer to an indicator light rather than a digital display screen	Must match "LED display"/"LED screen" rather than just "LED"

Category-specific experience: Wall Charger / Charger Block

Dimension	Parsing Key Points	Regex/Rules
Power	Prioritize matching explicit W values; when no W value, USB-A single port defaults to ≤12W; if only "PD"/"Fast Charging" is labeled, need product_detail confirmation	(\d+\.?\d*)\s*[Ww]
Number of ports	Distinguish "port count" from "pack count":2 port = 2 ports,2 pack = 2-pack	"dual"=2 ports, "3 port"=3 ports, number + port
Port type	Only annotate two categories: USB-C / USB-C+USB-A; pure USB-A products are extremely rare (have exited the mainstream)	Default is USB-C; those containing "USB-A"/"USB A" are marked as hybrid type
With cable	"with cable"/"with cord"/"built-in cable" = with cable; note the distinction between "charger with cable" and "charging cable as standalone item"	Keyword matching
Pack count (Pack)	(\d+)\s*-?\s*[Pp]ack Extract; if there is no Pack annotation, default to 1 pack	Regex extraction
GaN	Title contains "GaN"/"Gallium Nitride" = Yes	Case-insensitive
Foldable prongs	"foldable"/"fold"/"foldable plug" = Yes	Keyword matching
Pitfall	"2 Pack" vs "2 Port" is the most commonly confused; "USB C Charger Block 2 Pack" = 2-pack single-port, not 2-port	Requires combined context to determine
Pitfall	USB-A products whose titles have no W value are usually 5V/2.1A=10W or 5V/2.4A=12W, requiring product_detail to confirm	V×A calculation
Pitfall	A "40W" title may be a total power of "20W × 2 port", or it may be 40W for a single port; need to check the number of ports	Determine in conjunction with the number of ports

Rules for Using the Experience Library

1. Before executing Step 1.5, first consult the experience entries for the corresponding category in this section
2. When a new pitfall is discovered, record it at the end of the research report, and merge it back into this section later
3. First research on a category, the experience library may be empty; after the research is completed, at least 3 experience entries must be added
4. Confidence annotation: Any product matching the above pitfall entries is automatically marked as "low confidence" and enters the product_detail verification queue

---

Standard output directory structure (P2)

Standard output file structure for targeted category analysis (Scenario 4):

outputs/market-research/{brand}/{品类}/{version}/
├── top100_raw.json              # 原始 Top100 数据（category_report 直接输出）
├── top100_parsed.json           # 属性标注后的 Top100 数据（Step 1.5 输出）
├── uncertain_products.json      # 需 product_detail 验证的产品列表
├── cross_analysis.json          # 交叉分析结果（Step 1.6 输出）
├── voc_analysis.json            # VOC 差评分析结果
├── {date}_{site}_{品类}_市场调研报告_{version}.md     # 完整 MD 报告
├── {date}_{site}_{品类}_市场调研_数据_{version}.xlsx   # Excel 数据（多 Sheet）
├── {date}_{site}_{品类}_精简报告_{version}.html        # ⛔ HTML 精简报告（三件套必出）
├── parse_top100_dimensions.py   # 标题解析脚本（可选，复杂品类用）
├── apply_overrides.py           # 手动修正脚本（可选）
├── cross_analysis.py            # 交叉分析脚本（可选）
└── export_to_excel.py           # Excel 导出脚本

Among them, {version} is in the format v{N}_{YYYYMMDD}(such as v2_20260228), facilitating version management for multiple research efforts on the same category.

---

Report and Data File Storage

Three types of files must be output at the same time (⛔ the three-piece set must be produced)(consistent with market-comparison and the "External Data Calling Specification"): MD report + multi-Sheet Excel + HTML streamlined report, so that the person in charge can verify item by item and ASIN by ASIN, andsources are traceable。

Type	Format	File naming	Purpose
Report	.md	[日期]_[站点]_[关键词]_选品报告.md	Readable conclusions and recommendations
Data	.xlsx (multiple Sheets)	[日期]_[站点]_[关键词]_选品数据.xlsx	Verifiable, pivotable, and checkable item by item; the meaning and source of each Sheet are clear
⛔ Streamlined	.html	[日期]_[站点]_[关键词]_精简报告.html	Quickly browse key conclusions, can be opened and shared directly in a browser

HTML Streamlined Report Output Specification(⛔ unified across all categories, referencing the level of power bank v2 / charger):

The HTML streamlined report must be consistent with the same-source data as the MD/Excel, andthe structure, style, and sections must be complete, a crude version consisting only of "one paragraph + simple table" is prohibited. It must include the following sections and style conventions:

Block	Required	Content requirements	Style/Component
Header	⛔	Main title (category + market research) + subtitle (brand · site · date · version)	Centered; main title 28px; subtitle gray 14px
Market overview	⛔	4–8 core KPIs (Top100 monthly sales volume, monthly sales revenue, average price, China seller share, Top3 concentration, new product share, average rating, etc.)	KPI card grid(kpi-grid + kpi-card): each card label + value + note; specific numbers, vague terms such as "about" or "a small amount" are prohibited
Multidimensional product distribution	⛔	3–6 attribute dimensions for the category, each with "main segment / sales share" + "secondary segment / share" + a "key insight" column	Table: headers dimension, main segment, sales share, secondary segment, share, key insight; numbers are specific values
Consumer pain points	⛔	Top 5–6 negative reviews categorized by dimension, each: title + frequency/share (optional) + brief description	Pain point card grid(pain-grid + pain-card): ranking circle badge + title + frequency + desc; an insight box may be added to summarize brand opportunities
Supply-demand gap/opportunity whitespace	⛔	3–5 high-value whitespace or thin-supply combinations derived from cross-analysis; dimension combination, status (whitespace/thin supply), number of competitors, why it is worth attention	Table + gap-tag(empty/scarce) mark status
Brand/competitor landscape	⛔	Top 5–10 brands: brand, SKU count, monthly sales volume, share, positioning, implications for us	Table; must have clear conclusions, not merely copy the brand list
Barrier to entry assessment	⛔	Six types of barriers: Review / capital / technology / compliance / supply chain / brand, including level, cost/time, prerequisites	Table + conclusion paragraph
Go / No-Go scorecard	⛔	5-dimension scoring, weighted total score, conclusion, entry prerequisites, Top3 risks and mitigation	Scoring table + conclusion box
Brand recommendations	⛔	Product matrix or strategy recommendations (may be by Tier1/Tier2 or a unified strategy table); specifications, price band, one sentence on differentiation	Strategy card(tier-card) orTable; consistent with the recommendations in the MD report
Footer	⛔	Data source (Sorftime MCP), collection date, full report .md and .xlsx file names	Centered, small text, gray, border-top

Style conventions: use CSS variables to unify primary colors and grayscale (such as --blue, --gray-100); container max-width 960px, padding 40px 24px; tables with rounded corners, zebra hover, header background; responsive: two-column KPI on small screens, single-column pain points.Reference implementation: use the public example HTML structure output by the current task as the baseline, and do not reference brand-specific historical case paths.

Self-check: before delivery, confirm that the HTML contains the above 6 required blocks and has no vague expressions such as "a small amount" or "about"; consistent with the data in the MD report in the same directory.

Storage location: unified as outputs/market-research/[品牌名]/[品类slug]/[version]/; when the brand is not specified, it is recommended to use outputs/market-research/_draft/[品类slug]/[version]/. Do not scatter formal deliverable files directly in the repository root directory.

Excel Multi-Sheet Structure(must includeData Source Description、SummaryandDetails; any terms such as "Top100" must have their meanings distinguished in the Data Source Description):

Sheet Name	Type	Data Meaning (must be stated in the "Data Source Description")	Main Fields
Data Source Description	Required	Source and meaning of all Sheets in this file	Sheet name, data source tool, data meaning, key parameters, data acquisition date
Market Overview	Summary	Category + keyword summary metrics (category_search + keyword_detail)	Category name, NodeId, Top100 monthly sales volume, Top100 monthly sales amount, average price, ..., data acquisition date
Category Sales Top100_Details	Details	Category Sales Top100 Ranking(category_report, top 100 products in that category by sales volume)	ASIN, title, brand, seller, price, monthly sales volume, monthly sales amount, review count, star rating, ..., data source_tool, data source_meaning
Attribute Annotation_Top100	Details (Step 1.5)	Structured attribute annotation results for Top100 products	ASIN, title, brand, [attribute dimension columns], confidence, verification method (title/product_detail/override), data source_tool
Cross Analysis_Matrix	Analysis (Step 1.6)	Dimension cross-tabulation matrix data	Dimension A, Dimension B, product count, total monthly sales volume, total monthly sales amount, average price
Cross Analysis_Opportunity Gaps	Analysis (Step 1.6)	Supply-demand gaps and opportunity gaps	Dimension A value, Dimension B value, product count, judgment (blank/thin supply/high demand low supply), Top3 brand share
Keyword Organic Position Products_Details	Details	Top N products in organic search positions for a keyword(keyword_search_results, not category ranking)	ASIN, title, brand, price, monthly sales volume, review count, ..., data source_tool, keyword, data source_meaning
Potential Products_Details	Details	Potential product list (potential_product)	ASIN, title, brand, price, monthly sales volume, review count, potential index, data source_tool, data source_meaning
Competitor Negative Review Summary	Details	Negative review summary for a certain ASIN (product_reviews, reviewType=Negative)	ASIN, review type, pain point dimension, summary or high-frequency words, data source_tool, data source_meaning
Brand_Competitive Landscape	Required	Top brands and competitive role landscape	Brand, SKU count, monthly sales volume, share, role positioning, implications for target brand
Competitor Selection Logic	Required (if negative review analysis)	Competitors selected for negative review analysis and reasons for selection	ASIN, Brand, Reason for Selection, Competitor Type (Volume Benchmark/Functional Differentiation Representative/Price Band Coverage/Pain Point Reference), Coverage Dimensions, Data Source_Tool
Keyword Comparison_Segmented	Required	Multi-dimensional keyword comparison (Head Terms/Attribute Terms/Specification Terms/Scenario Terms)	Keyword, Dimension, Monthly Search Volume, CPC, Number of Organic Placement Products, Average Number of Reviews on First Page, Data Source_Tool
New Product Analysis	Required (Step 1.7)	Distribution and Trends of New Products (≤6 months) in Top100	ASIN, Title, Brand, Launch Date, Days Since Launch, Monthly Sales Volume, Monthly Sales Revenue, Price, [Attribute Dimension Columns], New Product Friendliness Rating, Data Source_Tool
Barrier to Entry Assessment	Required	Summary of Six Types of Barriers to Entry and Prerequisites for Launch	Barrier Type, Level, Data Anchor, Estimated Cost, Estimated Time, Implication for Target Brand
Go-NoGo Scorecard	Required	Five-Dimensional Weighted Scoring and Conclusion	Dimension, Weight, Score, Basis, Weighted Score, Total Score, Decision
1688 Reference	Details	1688 Similar Products (ali1688_similar_product)	Title, Price, Link, Data Source_Tool, Data Source_Meaning

Data Source Description Example Row：

Sheet Name	Data Source Tool	Data Meaning	Key Parameters	Data Retrieval Date
Category Sales Top100_Details	mcp_sorftime_category_report	Category Sales Top100 Ranking (Top 100 products by real-time sales in this category)	amzSite=US, nodeId=xxx	2026-02-12
Keyword Organic Placement Products_Details	mcp_sorftime_keyword_search_results	Top 50 products in organic search placements for the keyword "portable charger"	amzSite=US, searchKeyword=portable charger	2026-02-12

Naming and Meaning：

• "Category Sales Top100" = returned by category_reportThe top 100 products in this category sorted by sales。
• "Keyword XXX Organic Placement" = returned by keyword_search_resultsProducts in organic placements under that keyword search. The two must not be used interchangeably; wherever Top100/organic placement etc. appears in the report and Excel, it must be consistent with the data source description.
• Each detail Sheet is recommended to include the columns "Data Source_Tool" and "Data Source_Meaning", or at least have a corresponding row in "Data Source Description".

Generation Method: By default, use the skill's built-in script; no longer require manually assembling MD / HTML / Excel separately.

Unified Data Package Format (for render_deliverables.py use)

v2 Format (Recommended)

{
  "schema_version": "2.0",
  "metadata": {
    "brand": "AORYVIC",
    "category": "wood-furniture-legs",
    "version": "v1_20260311",
    "date": "20260311",
    "site": "US",
    "keyword": "wood-furniture-legs",
    "created": "2026-03-11 16:20",
    "topic": "AORYVIC Wood Furniture Legs Sofa Legs",
    "type": "选品报告",
    "data_sources": [
      "sorftime MCP: category_report",
      "sorftime MCP: keyword_detail"
    ]
  },
  "chapters": {
    "ch01_executive_summary": { "conclusions": [...], "go_nogo_verdict": "GO", "one_line_summary": "..." },
    "ch02_market_overview": { "kpis": [...], "keyword_comparison": [...], "insight": "..." },
    "ch03_dimension_distribution": { "dimensions": [...] },
    "ch04_cross_analysis": { "matrices": [...] },
    "ch05_competitor_brands": { "competitor_selection_logic": [...], "brand_landscape": [...], "insight": "..." },
    "ch06_voc_pain_points": { "by_dimension": [...] },
    "ch07_opportunity_gaps": { "opportunities": [...], "scoring_method": "...", "insight": "..." },
    "ch08_strategic_recommendations": { "tiers": [...], "brand_strategy": "...", "timeline": "..." },
    "ch09_barriers_go_nogo": { "barriers": [...], "go_nogo_scorecard": [...], "verdict": "GO", "risks": [...] },
    "ch10_appendix": { "tool_calls": [...], "data_date": "...", "files": [...] }
  },
  "excel_sheets": {
    "数据来源说明": [{ "...": "..." }],
    "市场概况": [{ "...": "..." }]
  },
  "artifacts": {
    "top100_raw.json": [],
    "cross_analysis.json": []
  }
}

For the complete v2 Schema, see references/payload_schema_v2.md

v1 Format (Backward Compatible)

v1 payload contains report_markdown / report_html field, without schema_version and chapters. The renderer automatically detects and follows the old path.

Script Responsibilities

render_deliverables.py will automatically:

1. Write to the specified directory outputs/market-research/{brand}/{category}/{version}/
2. v2 generation (4 deliverable files):
   • {date}_{site}_{keyword}_市场调研报告_{version}.md(rendered from chapters template)
   • {date}_{site}_{keyword}_精简报告_{version}.html(rendered from chapters template)
   • {date}_{site}_{keyword}_可视化看板_{version}.html(Dashboard, building view-model from chapters)
   • {date}_{site}_{keyword}_市场调研_数据_{version}.xlsx
   • excel_sheets_data.json、unified_payload.json and artifacts the raw/intermediate JSON declared in
3. Validation:
   • v2: all four deliverables present + chapters 10-chapter completeness + required fields for each chapter validated
   • Markdown contains YAML front matter
   • HTML contains 10 required sections
   • Excel first Sheet is 数据来源说明
   • file names and directory structure conform to skill specification

Definition of Done (DoD)

Execute python skills/zach-product-research/scripts/render_deliverables.py all --input <payload.json> afterward, the following must all be satisfied:

• command returns validate_ok
• official deliverable files are located in outputs/market-research/...
• v2: all four deliverables MD / HTML condensed / Dashboard kanban / XLSX exist
• Excel first Sheet is 数据来源说明
• key conclusions cited in the report are traceable in the corresponding Excel Sheet

Sheets corresponding to tools not called may be omitted or left with an empty list; estimated values must not be used to fill them.

• Every key number in the report should have a corresponding row/column in the corresponding Sheet; all conclusions can be checked item by item or ASIN by ASIN, and the source and meaning can be confirmed via the Data Source Description.

Self-test command

After each modification of scripts or templates, run at least once:

python skills/zach-product-research/scripts/render_deliverables.py all --input skills/zach-product-research/evals/files/sample_payload_minimal.json --root .

Only when it returns validate_okdoes it indicate that the delivery pipeline has not been broken.

Risks and boundaries

• This Skill does not do: it does not execute procurement, place orders, modify Listings, or operate ads
• Escalate to a human in the following cases：
  • When the Go/No-Go score falls in the CONDITIONAL GO range, a human decision is required
  • When data is abnormal (e.g., Top100 returns fewer than 50 items), mark the data as missing
  • For categories involving compliance/certification thresholds, remind the user to confirm
• risk-level: low — pure analysis/information gathering, does not affect funds or accounts

Upstream / Downstream

• Upstream(benefits-from): none, this Skill is the starting point of the chain
• Downstream(suggested follow-ups):
  • → /zach-competitor-deep-dive — deep competitor breakdown
  • → /zach-pricing-strategy — pricing strategy
  • → /zach-keyword-expansion — keyword expansion

Optional downstream integrations

This public version is only responsible for producing and validating the four-deliverable package, and does not include any private system write-back logic.

If you have your own workflow system, after delivery is complete you can connect these fields to:

• Feishu, Bitable, or an internal database
• Notion、Airtable、Google Sheets
• your own project kanban or product selection archive system

The minimum fields recommended for synchronization include:

• research keywords
• marketplace
• research date
• estimated monthly search volume
• mainstream price range
• estimated gross margin
• Go / No-Go
• delivery directory
• report file name
• Excel file name
• Dashboard file name

After completion

Report completion status (choose one of four):

• DONE — all four deliverables passed validate_ok
• DONE_WITH_CONCERNS — delivery completed but data has gaps (e.g., Top100 has fewer than 100 items)
• BLOCKED — Sorftime MCP unavailable or category ID cannot be located
• NEEDS_CONTEXT — user did not provide keywords/category/marketplace