feat(market-research): add research-angles, scoring, and report rubrics

plugins/market-research/skills/market-research/references/report-template.md

@@ -0,0 +1,44 @@
+# Market Research Report Template
+
+Fill every section. Write to `./work/market-research/research-<YYYY-MM-DD>.md`.
+
+---
+
+# Market Research — <YYYY-MM-DD>
+
+## Run parameters
+- Angles this run: <categories / regions / niche lens chosen in Phase 0>
+- Focus argument: <the user's focus, or "none">
+- Sources: App Store RSS (<feeds/regions pulled>) + web search (<themes>)
+- Candidates after history exclusion: <N> (history had <M> prior suggestions)
+
+## Top candidates (ranked)
+
+| # | Name | Category | Clone | Market | Monet. | Niche | **Total** | Why now |
+|---|------|----------|------:|-------:|-------:|------:|----------:|---------|
+| 1 | …    | …        |    85 |     80 |     75 |    60 |      **79** | one-line trend rationale |
+| … |      |          |       |        |        |       |           |         |
+
+(At least 10 rows.)
+
+## Candidate detail
+
+For each of the top candidates:
+
+### <name>
+- **Package (if known):** <com.x.y or "to resolve">
+- **What it does:** <1–2 sentences>
+- **Why now:** <trend signal: chart movement, news, dated incumbent…>
+- **Incumbents:** <who already does this and how weak/strong>
+- **Monetization:** <ads / IAP / subscription; ARPU note>
+- **Scores:** clone <>, market <>, monetization <>, niche <> → **total <>**
+- **Clone risk flags:** <heavy ML / native / content moat / none>
+
+## Recommended picks
+
+Top 3 to send to clone-app first, with one sentence each on why they lead.
+
+## Next step
+
+The user picks one or more candidates; each chosen candidate is resolved to a
+Google Play package/URL and handed to the `clone-app` skill for full feasibility.

plugins/market-research/skills/market-research/references/research-angles.md

@@ -0,0 +1,51 @@
+# Research Angles
+
+A rotating menu of search angles. Each run picks a DIFFERENT combination so
+results vary run-to-run (paired with history exclusion). Do not use the same
+combination two runs in a row — vary at least the category and the region.
+
+## How to rotate
+
+1. Read `./work/market-research/history.json` if present; note the angles used
+   recently (the `run_id` encodes the angle — see SKILL Phase 0).
+2. Pick **2–3 categories**, **1–2 regions**, and **1 niche lens** you did NOT use
+   last run. If a focus argument was passed to the command, force one category to
+   match it.
+3. Combine into concrete searches in Phase 1.
+
+## Categories
+
+- Hyper-casual games
+- Puzzle / word games
+- Productivity & utilities
+- Finance / fintech
+- Health & fitness
+- Education / kids
+- Photo & video editing
+- AI tools (chat, image, voice)
+- Social & community
+- Lifestyle / habit
+
+## Regions (App Store RSS region codes)
+
+- `us` (United States)
+- `gb` (United Kingdom)
+- `br` (Brazil — LATAM signal)
+- `in` (India)
+- `tr` (Türkiye)
+- `id` (Indonesia)
+- `de` (Germany)
+
+## Niche lenses
+
+- Underserved language/region (few quality localized apps)
+- Dated incumbent (top app last updated > 1 year ago)
+- Single-feature breakout (one job done very well)
+- Rising trend (news/ProductHunt/Reddit chatter in the last ~90 days)
+- Monetization mismatch (popular but weakly monetized → headroom)
+
+## App Store RSS feeds to pull (via fetch-charts.py)
+
+- `topfreeapplications` — demand/popularity signal
+- `topgrossingapplications` — monetization signal
+- `toppaidapplications` — willingness-to-pay signal

plugins/market-research/skills/market-research/references/scoring-guide.md

@@ -0,0 +1,43 @@
+# Scoring Guide
+
+Score every candidate 0–100 as a weighted composite. Three PRIMARY components
+(cloneability, market opportunity, monetization fit) plus a secondary tiebreaker
+(niche gap). Show the component scores, not just the total, so picks are auditable.
+
+## Components & weights
+
+| Component | Weight | What it measures |
+|---|---|---|
+| Cloneability | 35% | How cheaply this rebuilds with clone-app + AI. |
+| Market opportunity | 35% | Demand, growth, and incumbent weakness. |
+| Monetization fit | 20% | Ads/IAP friendliness and category ARPU. |
+| Niche gap (tiebreaker) | 10% | Underserved region/language/segment. |
+
+Total = 0.35·clone + 0.35·market + 0.20·monetization + 0.10·niche, each subscore 0–100.
+
+## Scoring each component (0–100)
+
+**Cloneability** — higher = easier:
+- 80–100: simple CRUD/utility, few backend endpoints, no heavy ML, standard UI.
+- 50–79: moderate backend, some real-time or media, mainstream third-party SDKs.
+- 0–49: heavy ML/on-device models, complex real-time/multiplayer, deep native, large content moat.
+
+**Market opportunity** — higher = better:
+- 80–100: strong/growing demand, dated or weak incumbents, clear unmet need.
+- 50–79: healthy demand, beatable incumbents.
+- 0–49: saturated, dominated by entrenched well-funded players.
+
+**Monetization fit** — higher = better:
+- 80–100: category with proven ads+IAP and high ARPU (casual games, utilities).
+- 50–79: monetizable but moderate ARPU.
+- 0–49: hard to monetize / users expect free.
+
+**Niche gap** — higher = more underserved:
+- 80–100: clear language/region/segment with no quality option.
+- 0–49: well served everywhere.
+
+## Output per candidate
+
+For each candidate keep: `name`, `package` (if resolved), `category`, the four
+subscores, the weighted `total`, and a one-line rationale. Rank by `total`
+descending. Produce at least 10 candidates AFTER history exclusion.