zach-search-term-report-analyzer

Amazon search term report analysis (v2)

How it works

v2 separates deterministic computation from semantic judgment:

搜索词报告
  → Stage A：清洗、7/14/30 天聚合、词根聚类、硬标签
  → Stage B：AI 助手或人工完成词根语义分类
  → Stage C：严格校验、词根决策继承、六类结果渲染

Root inheritance is used to handle low-sample long-tail terms: when a single search term has insufficient samples but its root has sufficient samples, the term inherits the root-level judgment; when both the term and the root have insufficient samples, it enters the low-volume long-tail pool pool, aggregated and monitored but not disguised as pending determination.

Required inputs

Parameter	Required	Default value	Description
Search term report	Yes	—	CSV / XLSX / XLSM / XLS
ASIN	Yes	—	Analyze only one ASIN at a time
Brand	Yes	—	Used for brand term hard labels and output naming
Target ACOS	Yes	—	Use a decimal, e.g., 0.20
Site	No	US	Used for optional Listing context scraping
Report type	No	Auto-detect	SP / SB / SD
Time window	No	7,14,30	Comma-separated
Listing context	No	Empty	A local Markdown / text snapshot can be passed in

If the report contains multiple ASINs, first list the candidates from the cleaned metadata, then have the user select one; do not mix them in the analysis. If the target ACOS, brand, or ASIN is missing, it must be supplied; do not substitute hidden default values.

Local reference

• references/architecture.md — v2 pipeline, data contract, and decision order
• references/field_mapping.md — SP / SB / SD field mapping
• references/decision_rules.md — operational explanation of decision rules
• references/term_classification.md — Stage B classification enums and JSON schema
• references/output_template.md — six output types and completion signals
• scripts/prepare_search_term_analysis.py — Stage A
• scripts/finalize_search_term_report.py — Stage C
• scripts/clean_search_term_report.py — cleaning foundation
• scripts/fetch_listing_context.py — optional Listing context scraping

Stage A: Prepare the analysis workbook

python3 skills/zach-search-term-report-analyzer/scripts/prepare_search_term_analysis.py \
  <input_file> \
  --asin B0XXXXXXXX \
  --brand ExampleBrand \
  --site US \
  --target-acos 0.20 \
  --windows 7,14,30 \
  --listing-context-file <optional-listing-context.md> \
  --output-dir outputs/search-term-report-analyzer/ExampleBrand/intermediate/

--listing-context-file and --report-type are both optional parameters; remove the corresponding command-line arguments when not in use.

Stage A only performs reproducible computations:

• Standardize fields, search terms, and numeric formats
• Identify non-empty numeric values that cannot be parsed; silent zeroing out is prohibited
• Aggregate by 7/14/30-day windows and recalculate CTR, CVR, ACOS, and ROAS
• Cluster search term roots
• Mark the deterministic asin_term and brand_term

It generates in the intermediate directory:

• workbook.json: term, root, window metrics, and classification requests
• roots_for_review.md: table of roots to classify, sorted by spend

Stage B: Complete root classification

Read roots_for_review.md、workbook.json the Listing context in and references/term_classification.md, for classification_request.roots_to_classify fill in each root:

• category
• relevance
• one-sentence note
• optional needs_listing_check

Output root_classifications.json. Example structure:

{
  "asin": "B0XXXXXXXX",
  "classified_by": "ai_assistant",
  "listing_context_source": "workbook.meta.listing_context",
  "roots": {
    "portable karaoke": {
      "category": "core_category_term",
      "relevance": "high",
      "note": "与目标商品的核心用途直接一致",
      "needs_listing_check": false
    }
  },
  "term_overrides": {}
}

Classification discipline:

1. Do not use uncertain_term, category and relevance must be provided.
2. All root terms to be classified must be covered; missing even one will cause Stage C to fail.
3. needs_listing_check Only used for the few root terms that genuinely depend on page capabilities to be judged.
4. Only write this when the member terms clearly deviate from the root term's semantics term_overrides。
5. Negative term judgments must simultaneously consider relevance, sample size, and Listing support, and must not be mechanically negated based on a single click.

Stage C: Generate formal results

python3 skills/zach-search-term-report-analyzer/scripts/finalize_search_term_report.py \
  outputs/search-term-report-analyzer/ExampleBrand/intermediate/workbook.json \
  --classifications outputs/search-term-report-analyzer/ExampleBrand/intermediate/root_classifications.json \
  --output-dir outputs/search-term-report-analyzer/ExampleBrand/

When Stage C starts, it strictly validates classification coverage and enumeration values. After validation passes, each search term receives one primary decision, one decision basis tier basis, a confidence level, and a reason.

Output

The recommended output directory is outputs/search-term-report-analyzer/{brand}/：

File	Purpose
..._搜索词报告分析.md	Main report
..._搜索词分析明细.csv	Full term details
..._否词清单.csv	exact negative term candidates and root-level phrase suggestions
..._搜索词分析操作台.html	Interactive workbench with filtering, sorting, checking, and CSV export
..._搜索词分析汇报.html	Static reporting page for KPIs, decision distribution, and spend destination
..._run_summary.json	Acceptance metrics and file list

Both HTML files are self-contained single files with inlined data, no CDN, Webfont, external images, or runtime fetch, and can be opened directly in a browser.

Acceptance

Read run_summary.json and verify:

1. pending_ratio_terms and pending_ratio_spend are both no higher than 0.10; any excess must be explained.
2. pool The term count, clicks, spend, and orders for
3. All six categories of formal output exist, and neither HTML contains a "payload not injected" prompt.
4. Decision distribution, spend destination, the main report, and the CSV are mutually consistent.
5. The report distinguishes data facts from analytical inferences and labels the source files and time range.

Risks and boundaries

• This skill only outputs suggestions and does not automatically modify ad budgets, bids, match types, or negative terms.
• When fields are insufficient, do not force ACOS / CVR conclusions; when SB / SD lack order or sales fields, only make judgments supported by the available fields and state the limitations.
• When ASINs are mixed up, products are mixed, classification coverage is incomplete, core fields are missing, or pending exceeds the limit, escalation to manual review is required.
• Any actual ad modification should be executed through the corresponding advertising platform after user confirmation.

Legacy compatibility entry point

scripts/analyze_search_term_decisions.py is temporarily retained for existing automation transitions, but is deprecated. New tasks should only use Stage A → Stage B → Stage C; the legacy entry point will be removed in a future major version.