• "how was last month?" → extract from monthly_trend
• "how was last year?" → 365d data
• "how was Q4 last year?" → extract from monthly_trend
• "how's retention looking?" → customer metrics focus

--period 30d

--period 90d

--period 365d

--period 30d

• Answer from the best available trailing window data
• State that exact calendar-month/quarter breakdown is not available
• Suggest running a full review for deeper analysis

• Present absolute values (revenue, orders) for the requested period
• Calculate its share of annual revenue (seasonality concentration)
• Compare against Q1-Q3 average for relative scale
• Add 365d overall YoY growth rate as context
• Do not mention the absence of YoY comparison (follow Handling Incomplete Data rules — omit what you can't measure)

1. Direct answer (2-3 sentences with key numbers from review.json)
2. Supporting context (1-2 observations that add nuance — tensions, comparisons)
3. One actionable takeaway (if warranted by the data)

• Order ID, Order date, Customer ID (or email)
• Revenue (after discounts, before tax/shipping)
• Quantity, SKU/Product ID
• Discount amount (if available)

~/.claude/skills/ecom/bin/ecom review orders.csv --output <output-dir>
~/.claude/skills/ecom/bin/ecom review orders.csv --period 90d --output <output-dir>

~/.claude/skills/ecom/bin/ecom review orders.csv --output <output-dir>

1. Period analysis -- computes KPIs for each time period (30d, 90d, 365d) with prior-period comparisons, decompositions, and trend detection.
2. Health checks -- evaluates ~30 checks across Revenue, Customer, and Product. Each check produces a pass/watch/fail signal with severity weighting. These power the 🟢/🟡/🔴 markers in the KPI tree.

review.json

review_{period}.json

1. Read

   review.json

   (or

   review_{period}.json

   for period-specific runs)
2. Load reference files on demand (see Reference Files below)
3. Write REVIEW.md (or

   REVIEW_{PERIOD}.md

   ) following the Output Format below

• periods

  only contains keys for periods where

  data_coverage

  is

  true

• All

  _change

  fields are proportional change vs prior period (e.g., 0.08 = +8%)

• health.checks

  contains every check result;

  health.top_issues

  is a filtered/sorted subset (fail and watch only, max 10, sorted by severity × impact)

• action_candidates

  are suggestions from Python; Claude refines, merges, and rewrites them in business language for the report

• monthly_trend

  contains only months with actual order data (no zero-fill for future months)

• monthly_trend

  entries with

  "partial": true

  have less than half the month's days with data
• When

  data_quality

  is non-empty, mention relevant warnings in Data Notes

Path:

references/

• review-narratives.md

  -- Narrative templates by health level and growth trajectory, finding templates, period-specific guidance. Always load.

• finding-clusters.md

  -- Cluster model for grouping related issues into themes. Load to identify themes.

• recommended-actions.md

  -- Actionable recommendations per check with timeline and impact range. Load for watch/fail checks.

• impact-formulas.md

  -- Revenue impact formulas with worked examples. Load when estimating impact.

• health-checks.md

  -- Check definitions (R/C/P) with thresholds and interpretation.

• benchmarks.md

  -- D2C ecommerce KPI benchmarks.

1. Executive Summary -- narrative blockquote (4-6 lines) + Scoreboard table
2. 30d Pulse section (if data available) -- KPI tree + max 1 finding
3. 90d Momentum section (if data available) -- KPI tree + drivers + max 2 findings
4. 365d Structure section (if data available) -- KPI tree + drivers + max 3 findings
5. Action Plan -- max 5 items grouped by time horizon + Guardrails
6. Data Notes -- 2-4 lines

• Sections MUST appear in this order. Do NOT reorganize by theme.
• Period sections MUST use the KPI tree format with emoji markers.
• Do NOT create standalone sections like "What's Working Well" or "Issues to Address".
• Positive signals belong in Executive Summary narrative and KPI tree markers.

[North Star result + trend across periods]
[What's working: 1-2 strengths confirmed by data -- 80/20 rule]
[What needs attention: the key tension/risk, with data]
[Most important action, with timeline]

Revenue reached $1.38M for the year (+25.7% YoY), but growth is decelerating -- the last 90 days grew only 8% vs prior 90 days, and last month was flat (+0.3%). Growth depends on existing customer AOV increases (+14.8%), while new customer acquisition has stalled (share: 42.3%, unchanged). Reallocate 20% of retention budget to acquisition channels by end of this month, targeting CPA below $XX.

Immediate (from 30d signals)
1. ...

This Month (from 90d findings)
2. ...

This Quarter (from 365d insights)
3. ...

• What (one concrete sentence)
• Why (reference specific data)
• When (specific deadline)
• Success metric (measurable)

Guardrails: [2-3 metrics that must not deteriorate while executing above actions]

Example: AOV must stay above $X | Repeat purchase rate must not drop below X% | Discount rate must stay under X%

• Revenue definition (from

  metadata.revenue_definition

  )
• Data period and order count
• Periods included/omitted

• Confirm or contradict across periods. Don't let periods exist in isolation.
• Zoom in: If 90d shows a break, check 30d for continuation.
• Never repeat a finding across periods. State once at the structural level.
• Executive Summary synthesizes, does not summarize sequentially.

• What is: 1 sentence. Quantitative fact. No interpretation.
• Why it matters: Data-backed tension. Must show contrast ("despite", "however"). Abstract concerns like "growth must be validated" are PROHIBITED.
• What to do: Direction and rationale only — 1 sentence. Deadlines and success metrics belong in the Action Plan. "Consider", "improve", "optimize", "explore" are PROHIBITED.

What is:       Annual revenue grew 25.7% YoY.
Why it matters: However, despite a 25.4% reduction in discount rate, new customer
               revenue share remains at 42.3% -- growth depends entirely on
               existing customer AOV increases (+14.8%).
What to do:    Reallocate retention budget toward acquisition channels to diversify growth sources.

What is:       Revenue grew 25.7%.
Why it matters: Rapid growth must be validated. <-- no data, no tension
What to do:    Consider improving acquisition. <-- banned verb, no deadline

• Omit what you can't measure. No N/A, no empty sections.
• Don't apologize. Never say "unfortunately..."
• Shorter data = shorter report.
• All gaps noted in Data Notes only.

• Write entire report in ONE language (match user's prompt/store language)
• Data Notes follows same language as body

• All numbers MUST come from review.json or be derived from its values
• Do NOT reference external sources (Shopify Analytics, GA, etc.)
• If additional data would help, note as recommended investigation in "What to do"
• PROHIBITED: "CVR from Shopify shows 2.1%" (CVR not in review.json)
• ALLOWED: "Investigate CVR in Shopify Analytics to determine root cause"

• When

  data_quality

  array is non-empty, mention relevant warnings in Data Notes
• Do NOT present partial-month MoM as real performance signals

• Never present numbers without interpretation
• Always explain why, not just the value
• Specific, actionable recommendations only
• Business language, not jargon (explain terms on first use)
• Connect related findings into systemic patterns
• No internal check IDs in the report
• No check counts in the report
• No repeated findings across sections
• Finding Quality Standards on every finding
• Guardrails on every action plan
• 80/20 rule: ~80% confirmation (builds trust), ~20% surprise (drives action)

Each check returns pass / watch / fail. These power the 🟢🟡🔴 KPI tree markers. Check definitions in

references/health-checks.md

. Do NOT use numeric scores, letter grades, or percentage-based health ratings.