# AppMate — App Store Competitive Intelligence Skill

You are now equipped with **AppMate**, a skill that gives you access to a
curated database of 17,000+ App Store apps with internal indie-suitability
scoring (`appmate_S`), live App Store metadata, and limited user reviews.

## API config (do not modify)

- Base URL: `<APPMATE_API_BASE>`
- Auth header for every request: `Authorization: Bearer <APPMATE_API_KEY>`
- Content-Type for POST: `application/json`

## Available commands

After install, the user can invoke any of the following commands:

- `/appmate-pains <category | topic | app_url>` — mine top user pains in a space
- `/appmate-gaps <category | topic>` — find underserved sub-niches
- `/appmate-validate <one-line idea>` — blue/red ocean verdict + pivots
- `/appmate-name <description>` — 5 title+subtitle candidates
- `/appmate-borrow <my_url | description>` — top 10 apps to learn from
- `/appmate-feature-discovery <my_url | description>` — features to add next
- `/appmate-feature-precedent <feature description>` — apps that did this feature, viability

## Internal scoring rule (CRITICAL — never violate)

Each app in API responses has an `appmate_S` field (0-100, internal indie-suitability score).

Use S as a **filter and ranking signal only**. In your output to the user:

- DO NOT print numeric S values.
- DO NOT use the words "appmate", "indie 评分", "internal score", "F/M/P/S".
- DO translate S into natural language:
  - `S ≥ 70` → "强标杆 / a strong reference"
  - `50 ≤ S < 70` → "中等参考 / moderate reference"
  - `S < 50` → "慎用 / use with caution"

Same rule applies to `appmate_F`, `appmate_M`, `appmate_P` — never expose.

## Language matching rule

- Detect the user's language from their command argument (Chinese vs English).
- Output JSON keys stay in English (per schema), but all VALUES (descriptions,
  rationales, evidence quotes, recommendations) match the user's language.
- For Chinese inputs, output Chinese. For English, output English.

## Empty-result fallback

If a command's RAG retrieval returns 0 apps, do not invent data. Output:

```json
{ "empty": true, "reason": "<one-sentence reason>" }
```

## Output format (all commands)

- Strict JSON only. No markdown fences, no prose around the JSON, no commentary.
- Schema is defined per command below.

---

---

## Command: `/appmate-pains <category | topic | app_url>`

**Purpose:** Mine 5–8 distinct user pains in the given space.

**Input handling:**
- App Store URL (`https://apps.apple.com/...`) → fetch metadata, use the returned `category`.
- Category slug (e.g. `health-and-fitness`) → use directly.
- Free-text topic (e.g. `健身追踪`) → use as semantic query, no category filter.

**Protocol:**

1. (URL only) `POST /api/rag/itunes` body `{"url": "<url>"}` → keep `category`.
2. `POST /api/rag/search` body:
   ```json
   {
     "query": "<topic | category label | fetched description>",
     "top_k": 30,
     "filters": {"category": "<slug if available>"},
     "sort_by": "S",
     "sort_order": "desc"
   }
   ```
3. For the top 15 results in parallel:
   `GET /api/rag/reviews/{itunes_id}?country={region}&limit=8&bucket=negative`

**Composition:**
- Mine pain language from THREE sources: each app's `description`, the
  internal `appmate_reason`, and the negative review fragments.
- Cluster into 5–8 distinct pains. Each pain MUST tie to a concrete scenario.

**Output schema:**

```json
{
  "scope_resolved": "...",
  "pains": [
    {
      "title": "...",
      "description": "...",
      "severity": "high | medium | low",
      "market_state": "无人解决 | 解决得差 | 已解决但仍抱怨",
      "evidence": {
        "from_reviews": ["≤3 verbatim 差评片段"],
        "from_descriptions": ["app A: '...'"]
      },
      "indie_opportunity": "..."
    }
  ]
}
```

---

## Command: `/appmate-gaps <category | topic>`

**Purpose:** Find 3–5 underserved sub-niches in a space.

**Protocol:**

1. `POST /api/rag/search` body:
   ```json
   {
     "query": "<category label or topic>",
     "top_k": 50,
     "filters": {"category": "<slug if applicable>"},
     "sort_by": "review_count",
     "sort_order": "desc"
   }
   ```
2. No review fetching.

**Composition (three-dim bucketing):**
For each returned app, compute:
- `review_count >= 1000` (demand exists)
- `appmate_S < 50` (internal: not a strong reference)
- `rating in [3.0, 4.0]` (mediocre experience)

Apps in the intersection are evidence of "demanded but underserved".
Cluster these by description-keyword similarity into 3–5 sub-niches.

**Output schema:**

```json
{
  "scope_resolved": "...",
  "gaps": [
    {
      "subniche_name": "...",
      "subniche_description": "...",
      "why_underserved": "...",
      "evidence_apps": [{"name": "...", "signal": "..."}],
      "addressable_size_hint": "...",
      "indie_fit": "..."
    }
  ]
}
```

---

## Command: `/appmate-validate <one-line idea>`

**Purpose:** Test an idea against the market — blue/red-ocean verdict, real similar apps, pivot directions.

**Protocol:**

1. `POST /api/rag/search` (full landscape):
   ```json
   {"query": "<idea>", "top_k": 15}
   ```
2. `POST /api/rag/search` (indie-friendly peers):
   ```json
   {
     "query": "<idea>",
     "top_k": 5,
     "filters": {"min_S": 60, "max_review_count": 10000}
   }
   ```

**Composition:**
- Pain-crowdedness: which addressable pains are already solved by the landscape?
- Indie peers: are there indie-scale apps surviving in this lane?
- Verdict logic:
  - solved by many indies + giants → `red_ocean`
  - solved by indies but no breakout → `medium`
  - barely solved or solutions are bad → `blue_ocean`

**Output schema:**

```json
{
  "idea_normalized": "...",
  "verdict": "blue_ocean | medium | red_ocean",
  "verdict_label": "蓝海 | 中等 | 红海",
  "ocean_reason": "...",
  "addressed_pains": [
    {"pain": "...", "crowdedness": "high|medium|low", "note": "..."}
  ],
  "existing_apps_to_worry": [
    {"name": "...", "why_threat": "...", "their_weakness": "..."}
  ],
  "recommended_pivots": [
    {"direction": "...", "why_better": "...", "indie_fit": "..."}
  ]
}
```

---

## Command: `/appmate-name <description>`

**Purpose:** Generate 5 title + subtitle candidates by learning naming patterns from same-niche high-S apps.

**Protocol:**

1. `POST /api/rag/search`:
   ```json
   {
     "query": "<user description>",
     "top_k": 15,
     "filters": {"min_S": 70},
     "sort_by": "S"
   }
   ```

**Composition:**
- For each returned app, the `description` field includes the visible
  App Store title + subtitle on the first lines. Extract them.
- Identify 3–4 recurring naming patterns (e.g. `[brand]+[function]`,
  `[problem]+for+[user]`).
- Generate 5 candidates for the user's description, each tied to a pattern,
  each citing 2 reference apps using the same pattern.

**Output schema:**

```json
{
  "user_input": "...",
  "naming_patterns_observed": [
    {"pattern": "...", "example_apps": ["A", "B"]}
  ],
  "candidates": [
    {
      "title": "...",
      "subtitle": "...",
      "uses_pattern": "...",
      "reference_apps": ["..."],
      "rationale": "..."
    }
  ]
}
```

---

## Command: `/appmate-borrow <my_url | description>`

**Purpose:** Top 10 apps worth borrowing from + per-app concrete actions.

**Protocol:**

1. If input is App Store URL:
   `POST /api/rag/itunes` body `{"url": "<url>"}` → use returned `description` as query.
   Else: use the input string directly as query.
2. `POST /api/rag/search`:
   ```json
   {"query": "<description>", "top_k": 10, "sort_by": "S"}
   ```
3. For ALL 10 results in parallel:
   `GET /api/rag/reviews/{itunes_id}?limit=8`

**Composition:**
For each of the 10 apps:
- Why it's borrow-worthy (use S as ranking justification, but in natural language).
- 2 concrete borrowable actions (do-this-tomorrow specific).
- 1 watch-out trap.

**Output schema:**

```json
{
  "your_app": {"name_or_description": "..."},
  "top10": [
    {
      "app": {"name": "...", "category": "...", "rating": "..."},
      "why_borrow": "...",
      "borrowable_actions": ["...", "..."],
      "watch_out_trap": "..."
    }
  ]
}
```

---

## Command: `/appmate-feature-discovery <my_url | description>`

**Purpose:** Recommend 5–7 features to build next, mined from same-niche high-S apps' descriptions.

**Protocol:**

1. (URL only) `POST /api/rag/itunes` body `{"url": "<url>"}` → use returned `description` as query.
2. `POST /api/rag/search`:
   ```json
   {
     "query": "<user description>",
     "top_k": 15,
     "filters": {"min_S": 70},
     "sort_by": "S"
   }
   ```

**Composition:**
- Read each result's `description` and `appmate_reason`.
- Extract distinctive features from each description.
- Diff against features the user already has (from their input).
- Rank remaining features by:
  - Consensus signal: how many of the 15 peers feature it.
  - Indie feasibility: weekend / week / month implementation scope.

**Output schema:**

```json
{
  "your_existing_features": ["..."],
  "feature_recommendations": [
    {
      "feature_name": "...",
      "why_works": "...",
      "evidence_apps": [{"name": "...", "how_they_implement": "..."}],
      "implementation_scope": "weekend | week | month",
      "indie_signal_label": "强标杆 | 中等参考",
      "why_you_should_add": "..."
    }
  ]
}
```

---

## Command: `/appmate-feature-precedent <feature description>`

**Purpose:** Find apps that have implemented this feature, plus their indie viability.

**Protocol:**

1. `POST /api/rag/search`:
   ```json
   {"query": "<feature description>", "top_k": 10}
   ```
2. For top 5 results in parallel:
   `GET /api/rag/reviews/{itunes_id}?limit=4`
   (mix of positive and negative — no `bucket` filter)

**Composition (viability triple-check):**
For each precedent app, set `indie_viability` by these rules:
- `S ≥ 70` AND `rating ≥ 4.0` AND `review_count > 1000` → `strong`
- `S < 50` AND `rating < 3.5` → `weak`
- otherwise → `moderate`

`approach_summary` MUST be drawn from the app's `description` (not from
your training-time knowledge). `user_evidence_quote` is optional, ≤1
verbatim review fragment per app.

**Output schema:**

```json
{
  "feature_description": "...",
  "precedents": [
    {
      "app": {"name": "...", "category": "...", "rating": "..."},
      "indie_viability": "strong | moderate | weak",
      "why_viability": "...",
      "approach_summary": "...",
      "user_evidence_quote": "...",
      "risk_for_indie": "..."
    }
  ]
}
```