@tydung26/product-kit 1.3.2 → 1.5.0

package/skills/market-intel/SKILL.md

@@ -11,14 +11,14 @@ license: MIT
 
 # Market Intel - Competitive Landscape Analysis
 
-Scope → competitor profiles → feature matrix → whitespace mapping → strategic recommendations.
+Automated competitor discovery across 4 platforms → structured analysis → dashboard-style report.
 
-**Principles:** Be honest about strengths and gaps | Actionable recs over generic summaries | Evidence over opinion
+**Principles:** Evidence over opinion | Honest about strengths and gaps | Actionable recs over generic summaries | Graceful degradation when data unavailable
 
 ## Usage
 
 ```
-/pkit:market-intel <product/feature/market>
+/pkit:market-intel <product idea or market description>
 ```
 
 **Do NOT use for:** Internal A/B decisions, roadmap planning (`/pkit:roadmap`), or feature prioritization.
@@ -26,16 +26,36 @@ Scope → competitor profiles → feature matrix → whitespace mapping → stra
 ## Workflow Overview
 
 ```
-[Scope Analysis] → [Competitor Profiles] → [Feature Comparison] → [Whitespace & Differentiation] → [Strategic Recs]
+[Scope] → [Search Platforms] → [Fetch & Extract] → [Analyze] → [Compare] → [Report]
 ```
 
-| Step          | Action                                       | Skip if          |
-| ------------- | -------------------------------------------- | ---------------- |
-| 1. Scope      | Define product, competitors, focus area      | Context provided |
-| 2. Profiles   | Build competitor profiles                    | —                |
-| 3. Compare    | Feature comparison matrix                    | —                |
-| 4. Whitespace | Gaps, table stakes, differentiation, threats | —                |
-| 5. Recommend  | 3 strategic bullets                          | —                |
+| Step       | Action                                          | Skip if          |
+| ---------- | ----------------------------------------------- | ---------------- |
+| 1. Scope   | Define product idea, competitors, focus area    | Context provided |
+| 2. Search  | Run crawler scripts on all 4 platforms          | —                |
+| 3. Parse   | Parse JSON output, merge and deduplicate        | —                |
+| 4. Analyze | Per-competitor analysis across all dimensions   | —                |
+| 5. Compare | Cross-competitor feature matrix + pricing       | —                |
+| 6. Report  | Generate dashboard-style MD report              | —                |
+
+## Helper Scripts
+
+Platform-specific crawler scripts are bundled in `scripts/` (relative to this SKILL.md).
+Each script fetches and parses data from one platform, outputting structured JSON to stdout.
+
+**Usage:** Run via Bash tool:
+
+```bash
+python3 {skill_dir}/scripts/search-app-store.py "<keywords>" [limit]
+python3 {skill_dir}/scripts/search-google-play.py "<keywords>" [limit]
+python3 {skill_dir}/scripts/search-product-hunt.py "<keywords>" [limit]
+python3 {skill_dir}/scripts/search-yc-launch.py "<keywords>" [limit]
+```
+
+- `{skill_dir}` = directory containing this SKILL.md
+- `limit` = max results per platform (default 5, max 10)
+- Output: JSON with `results[]` array (name, url, description, rating, pricing, reviews) and `errors[]` for non-fatal issues
+- **Run all 4 in parallel** for speed
 
 ## Step Details
 
@@ -43,79 +63,182 @@ Scope → competitor profiles → feature matrix → whitespace mapping → stra
 
 Ask if not provided:
 
-- What product/feature are we analyzing?
-- Who are the known competitors? (or: "I'll suggest some")
+- What product/feature/idea are we analyzing?
+- Who are known competitors? (or: "find them for me")
 - Focus area: pricing / features / UX / positioning / all?
-- Audience for this analysis: internal team, investors, exec?
+- How many competitors to analyze? (default 5–8, max 10)
+
+### Step 2 — Search Platforms
+
+**Primary method:** Run all 4 crawler scripts in parallel via Bash tool:
+
+```bash
+python3 {skill_dir}/scripts/search-app-store.py "{keywords}" {limit}
+python3 {skill_dir}/scripts/search-google-play.py "{keywords}" {limit}
+python3 {skill_dir}/scripts/search-product-hunt.py "{keywords}" {limit}
+python3 {skill_dir}/scripts/search-yc-launch.py "{keywords}" {limit}
+```
+
+Also run a general WebSearch: `{keywords} app alternatives competitors` to catch competitors not on these platforms.
+
+**Fallback (if scripts unavailable):** Use WebSearch with `site:` queries:
+
+| Platform     | Search Query Pattern                                  |
+| ------------ | ----------------------------------------------------- |
+| App Store    | `site:apps.apple.com {keywords}`                      |
+| Google Play  | `site:play.google.com/store/apps {keywords}`          |
+| Product Hunt | `site:producthunt.com/posts {keywords}`               |
+| YC Launch    | `site:ycombinator.com/launches {keywords}`            |
+
+### Step 3 — Parse & Merge Results
+
+Parse JSON output from each script. Each result contains:
+
+- `name`, `url`, `description`, `tagline`
+- `rating`, `reviewCount`
+- `pricing` (free, monthly, yearly, other)
+- `reviews[]` (text, rating, sentiment)
+- `errors[]` (non-fatal issues encountered)
+
+**Merge:** Deduplicate by product name across platforms. Prioritize entries with richer data (more reviews, pricing info). Check the `errors` array — note any platform issues in the final report.
+
+**If using WebSearch fallback:** WebFetch each result URL and manually extract the same fields.
+
+### Step 4 — Analyze Per Competitor
 
-### Step 2 — Competitor Profiles
+For each competitor, determine:
 
-For each competitor, create a profile:
+| Dimension          | What to assess                                          |
+| ------------------ | ------------------------------------------------------- |
+| Problem Solved     | Core pain point addressed                               |
+| Target Audience    | Primary user segment (role, context, company size)      |
+| Value Proposition  | Why users choose this over alternatives                 |
+| Killer Features    | Top 3 differentiating capabilities                      |
+| Strengths          | Top 3 things done well (from reviews + product page)    |
+| Weaknesses         | Top 3 gaps or pain points (from negative reviews/discussions) |
+| Review Sentiment   | Positive / Mixed / Negative + key themes                |
+| Pricing Model      | Free tier, monthly, yearly, lifetime, other tiers       |
 
-**[Competitor Name]**
+Base analysis on **actual data** from fetched pages, reviews, and discussions — not assumptions.
 
-- **Positioning:** How they describe themselves
-- **Target segment:** Who they primarily serve
-- **Pricing model:** Free/freemium/paid tiers (include price points if known)
-- **Key strengths:** Top 3 things they do well
-- **Key weaknesses:** Top 3 pain points or gaps
-- **Notable features:** Differentiated capabilities worth noting
+### Step 5 — Cross-Compare
 
-### Step 3 — Feature Comparison Table
+Build two comparison matrices:
 
-Create a markdown comparison table:
+**Feature Matrix** — identify 8–15 key features across all competitors:
 
-| Feature   | Us        | Competitor A | Competitor B | Competitor C |
-| --------- | --------- | ------------ | ------------ | ------------ |
-| [Feature] | ✓ / ✗ / ~ | ✓ / ✗ / ~    | ...          | ...          |
+| Feature   | App A     | App B     | App C     |
+| --------- | --------- | --------- | --------- |
+| [Feature] | ✓ / ✗ / ~ | ✓ / ✗ / ~ | ✓ / ✗ / ~ |
 
 Legend: ✓ = strong, ~ = partial/limited, ✗ = missing
 
-### Step 4 — Whitespace & Differentiation
+**Pricing Landscape** — normalize pricing across competitors.
 
-Identify:
+Then identify:
 
-- **Gaps no one fills well** (your opportunity)
-- **Table stakes** (must-have to compete)
-- **Our current differentiation** (honest assessment)
-- **Threats to watch** (competitors gaining momentum)
+- **Gaps no one fills well** — your opportunity
+- **Table stakes** — must-have to compete
+- **Emerging threats** — competitors gaining momentum
 
-### Step 5 — Strategic Recommendations
+### Step 6 — Generate Report
 
-3 bullets max. Be direct:
+Output a single markdown report using the template below. Save to the plan reports directory if available.
 
-- What to double down on
-- What to build to close gaps
-- What to monitor but not react to yet
+**Table width rule:** If >7 competitors, split the Competitor Dashboard into 2 tables (e.g., 1–5 and 6–10).
 
-## Output Format
+## Report Template
 
-```
-## Competitor Profiles
+```markdown
+# Market Intel Report: [Product Idea]
+
+> **Platforms searched:** App Store, Google Play, Product Hunt, YC Launch
+> **Competitors analyzed:** {count} | **Generated:** {date}
+
+## Competitor Dashboard
+
+| Aspect            | App A          | App B          | App C          |
+| ----------------- | -------------- | -------------- | -------------- |
+| Platform(s)       | PH, App Store  | Google Play    | YC Launch      |
+| Problem Solved    | ...            | ...            | ...            |
+| Target Audience   | ...            | ...            | ...            |
+| Value Proposition | ...            | ...            | ...            |
+| Killer Features   | ...            | ...            | ...            |
+| Strengths         | ...            | ...            | ...            |
+| Weaknesses        | ...            | ...            | ...            |
+| Rating            | 4.5★ (2.3k)   | 4.1★ (800)    | N/A            |
+| Review Sentiment  | Positive       | Mixed          | Positive       |
+
+## Pricing Landscape
+
+| App   | Free Tier | Monthly | Yearly | Other        | Notes         |
+| ----- | --------- | ------- | ------ | ------------ | ------------- |
+| App A | ✓         | $9      | $79    | —            | 14-day trial  |
+| App B | Freemium  | $12     | —      | Lifetime $199| —             |
+
+Use "Unknown" for pricing not found — never leave blank.
+
+## Feature Matrix
+
+| Feature      | A | B | C | D | E |
+| ------------ | - | - | - | - | - |
+| [Feature 1]  | ✓ | ✗ | ~ | ✓ | ✓ |
+| [Feature 2]  | ~ | ✓ | ✓ | ✗ | ~ |
+
+Legend: ✓ = strong, ~ = partial, ✗ = missing
 
-### [Competitor Name]
-- Positioning: ...
-- Target: ...
-- Pricing: ...
-- Strengths: ...
-- Weaknesses: ...
+## Strategic Insights
 
-[repeat]
+### What to Take
 
-## Feature Comparison
+| Insight | Evidence | Source |
+| ------- | -------- | ------ |
+| ...     | ...      | App A reviews |
 
-| Feature | Us | CompA | CompB |
-|---------|----|-------|-------|
+### What to Avoid
 
-## Whitespace & Differentiation
+| Anti-pattern | Why | Evidence |
+| ------------ | --- | -------- |
+| ...          | ... | App C 1-star reviews |
 
-**Gaps:** ...
-**Table stakes:** ...
-**Our differentiation:** ...
-**Threats:** ...
+### What to Do Uniquely
 
-## Strategic Recommendations
-1. ...
-2. ...
-3. ...
+| Opportunity | Gap in Market | Our Angle |
+| ----------- | ------------- | --------- |
+| ...         | No one does X well | ... |
+
+## Market Gaps & Threats
+
+| Type            | Finding |
+| --------------- | ------- |
+| Unfilled gap    | ...     |
+| Table stakes    | ...     |
+| Emerging threat | ...     |
+
+## Data Sources
+
+| Competitor | Platforms Found On     | URLs          |
+| ---------- | ---------------------- | ------------- |
+| App A      | Product Hunt, App Store| [links]       |
+| App B      | Google Play            | [links]       |
 ```
+
+## Graceful Degradation
+
+| Scenario                         | Action                                                    |
+| -------------------------------- | --------------------------------------------------------- |
+| Platform fetch blocked           | Use search snippet data, note in Data Sources             |
+| No results on a platform         | Note "No results on {platform}", continue with rest       |
+| >7 competitors analyzed          | Split Competitor Dashboard into 2 tables                  |
+| Pricing not found                | Mark as "Unknown", never leave blank                      |
+| Reviews unavailable              | Note "No reviews available", assess from description      |
+| Entire search yields <3 hits     | Ask user for more specific keywords or known competitors  |
+| WebSearch/WebFetch unavailable   | Ask user for competitor names and URLs, analyze from provided context |
+| Scripts not found / Node error   | Fall back to WebSearch + WebFetch method (see Step 2 fallback)       |
+| Script returns empty results     | Check `errors[]` in JSON, fall back to WebSearch for that platform   |
+
+## Follow-up
+
+Always end with:
+
+> "Report complete. Want me to go deeper on any competitor, or feed these insights into `/pkit:product-design` for a PRD?"

package/skills/market-intel/scripts/search-app-store.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""App Store crawler via iTunes Search API. Zero external dependencies.
+Usage: python3 search-app-store.py "<keywords>" [limit]
+Output: JSON CrawlResult to stdout
+"""
+
+import json
+import sys
+import urllib.request
+import urllib.parse
+from datetime import datetime, timezone
+
+
+def safe_fetch(url, timeout=10):
+    """Fetch URL with timeout and user-agent header."""
+    req = urllib.request.Request(url, headers={
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                       "AppleWebKit/537.36 (KHTML, like Gecko) "
+                       "Chrome/120.0.0.0 Safari/537.36",
+    })
+    return urllib.request.urlopen(req, timeout=timeout)
+
+
+def truncate(text, max_len=500):
+    return text[:max_len] + "..." if len(text) > max_len else text
+
+
+def fetch_reviews(track_id):
+    """Fetch recent reviews via iTunes RSS feed."""
+    reviews = []
+    try:
+        url = (f"https://itunes.apple.com/rss/customerreviews/"
+               f"id={track_id}/sortBy=mostRecent/json")
+        resp = safe_fetch(url)
+        data = json.loads(resp.read())
+        entries = data.get("feed", {}).get("entry", [])
+        for entry in entries[:6]:
+            content = entry.get("content", {}).get("label", "")
+            rating_str = entry.get("im:rating", {}).get("label", "")
+            if not content or not rating_str:
+                continue
+            rating = int(rating_str)
+            sentiment = "positive" if rating >= 4 else "negative" if rating <= 2 else "neutral"
+            reviews.append({
+                "text": truncate(content, 300),
+                "rating": rating,
+                "sentiment": sentiment,
+            })
+    except Exception:
+        pass
+    return reviews
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "Usage: python3 search-app-store.py <keywords> [limit]"}))
+        sys.exit(1)
+
+    query = sys.argv[1]
+    limit = 5
+    if len(sys.argv) >= 3:
+        try:
+            limit = max(1, min(int(sys.argv[2]), 10))
+        except ValueError:
+            limit = 5
+
+    errors = []
+    search_url = (
+        f"https://itunes.apple.com/search?"
+        f"term={urllib.parse.quote(query)}&entity=software&limit={limit}&country=us"
+    )
+
+    try:
+        resp = safe_fetch(search_url)
+        search_data = json.loads(resp.read())
+    except Exception as e:
+        print(json.dumps({
+            "platform": "app_store", "query": query,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "results": [], "errors": [f"iTunes API error: {e}"],
+        }, indent=2))
+        return
+
+    results = []
+    for app in search_data.get("results", []):
+        track_id = app.get("trackId", 0)
+        reviews = fetch_reviews(track_id)
+        price = app.get("price", 0)
+
+        results.append({
+            "name": app.get("trackName", ""),
+            "url": app.get("trackViewUrl", ""),
+            "description": truncate(app.get("description", "")),
+            "tagline": None,
+            "rating": round(app.get("averageUserRating", 0), 1) or None,
+            "reviewCount": app.get("userRatingCount"),
+            "pricing": {
+                "free": price == 0,
+                "monthly": None,
+                "yearly": None,
+                "other": app.get("formattedPrice") if price > 0 else None,
+            },
+            "features": [],
+            "reviews": reviews,
+        })
+
+    print(json.dumps({
+        "platform": "app_store",
+        "query": query,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "results": results,
+        "errors": errors,
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/market-intel/scripts/search-google-play.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Google Play Store crawler via HTML scraping. Zero external dependencies.
+Usage: python3 search-google-play.py "<keywords>" [limit]
+Output: JSON CrawlResult to stdout
+"""
+
+import json
+import re
+import sys
+import urllib.request
+import urllib.parse
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+
+
+def safe_fetch(url, timeout=10):
+    """Fetch URL with timeout and user-agent header."""
+    req = urllib.request.Request(url, headers={
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                       "AppleWebKit/537.36 (KHTML, like Gecko) "
+                       "Chrome/120.0.0.0 Safari/537.36",
+        "Accept-Language": "en-US,en;q=0.9",
+    })
+    return urllib.request.urlopen(req, timeout=timeout).read().decode("utf-8", errors="replace")
+
+
+def truncate(text, max_len=500):
+    return text[:max_len] + "..." if len(text) > max_len else text
+
+
+def extract_app_ids_from_search(html):
+    """Extract app IDs from Google Play search page HTML."""
+    # Google Play links: /store/apps/details?id=com.example.app
+    ids = re.findall(r'/store/apps/details\?id=([a-zA-Z0-9_.]+)', html)
+    # Deduplicate while preserving order
+    seen = set()
+    unique = []
+    for app_id in ids:
+        if app_id not in seen:
+            seen.add(app_id)
+            unique.append(app_id)
+    return unique
+
+
+def extract_json_ld(html):
+    """Extract JSON-LD structured data from HTML."""
+    matches = re.findall(
+        r'<script[^>]*type="application/ld\+json"[^>]*>(.*?)</script>',
+        html, re.DOTALL
+    )
+    for match in matches:
+        try:
+            data = json.loads(match)
+            if isinstance(data, dict) and data.get("@type") == "SoftwareApplication":
+                return data
+        except (json.JSONDecodeError, ValueError):
+            continue
+    return None
+
+
+def extract_app_details(html, app_id):
+    """Extract app details from a Google Play detail page."""
+    url = f"https://play.google.com/store/apps/details?id={app_id}"
+
+    # Try JSON-LD first (most reliable)
+    json_ld = extract_json_ld(html)
+    if json_ld:
+        name = json_ld.get("name", "")
+        description = json_ld.get("description", "")
+        rating = None
+        review_count = None
+        agg = json_ld.get("aggregateRating", {})
+        if agg:
+            try:
+                rating = round(float(agg.get("ratingValue", 0)), 1)
+                review_count = int(agg.get("ratingCount", 0))
+            except (ValueError, TypeError):
+                pass
+
+        price_text = json_ld.get("offers", {}).get("price", "0")
+        is_free = str(price_text) in ("0", "0.00", "")
+
+        return {
+            "name": name,
+            "url": url,
+            "description": truncate(description),
+            "rating": rating if rating else None,
+            "reviewCount": review_count if review_count else None,
+            "pricing": {
+                "free": is_free,
+                "other": None if is_free else str(price_text),
+            },
+            "features": [],
+            "reviews": [],
+        }
+
+    # Fallback: meta tags
+    name_match = re.search(r'<meta\s+property="og:title"\s+content="([^"]*)"', html)
+    desc_match = re.search(r'<meta\s+property="og:description"\s+content="([^"]*)"', html)
+    name = name_match.group(1) if name_match else ""
+    description = desc_match.group(1) if desc_match else ""
+
+    if not name:
+        return None
+
+    return {
+        "name": name.replace(" - Apps on Google Play", ""),
+        "url": url,
+        "description": truncate(description),
+        "rating": None,
+        "reviewCount": None,
+        "pricing": {"free": True},
+        "features": [],
+        "reviews": [],
+    }
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "Usage: python3 search-google-play.py <keywords> [limit]"}))
+        sys.exit(1)
+
+    query = sys.argv[1]
+    limit = 5
+    if len(sys.argv) >= 3:
+        try:
+            limit = max(1, min(int(sys.argv[2]), 10))
+        except ValueError:
+            limit = 5
+
+    errors = []
+    search_url = (
+        f"https://play.google.com/store/search?"
+        f"q={urllib.parse.quote(query)}&c=apps&hl=en&gl=us"
+    )
+
+    try:
+        search_html = safe_fetch(search_url)
+    except Exception as e:
+        print(json.dumps({
+            "platform": "google_play", "query": query,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "results": [], "errors": [f"Google Play search error: {e}"],
+        }, indent=2))
+        return
+
+    app_ids = extract_app_ids_from_search(search_html)[:limit]
+
+    if not app_ids:
+        errors.append("No app IDs found — page may be JS-rendered")
+        print(json.dumps({
+            "platform": "google_play", "query": query,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "results": [], "errors": errors,
+        }, indent=2))
+        return
+
+    results = []
+    for app_id in app_ids:
+        detail_url = f"https://play.google.com/store/apps/details?id={app_id}&hl=en&gl=us"
+        try:
+            detail_html = safe_fetch(detail_url)
+            entry = extract_app_details(detail_html, app_id)
+            if entry:
+                results.append(entry)
+        except Exception as e:
+            errors.append(f"Failed to fetch {app_id}: {e}")
+
+    print(json.dumps({
+        "platform": "google_play",
+        "query": query,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "results": results,
+        "errors": errors,
+    }, indent=2))
+
+
+if __name__ == "__main__":
+    main()