@opendirectory.dev/skills 0.1.34 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendirectory.dev/skills",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

package/registry.json

@@ -77,6 +77,16 @@
     "version": "1.0.0",
     "path": "skills/explain-this-pr"
   },
+  {
+    "name": "gh-issue-to-demand-signal",
+    "description": "Takes a competitor's public GitHub repo URL, fetches their open issues via the GitHub REST API, filters noise locally, clusters issues into 6 deman...",
+    "tags": [
+      "Developer Tools"
+    ],
+    "author": "opendirectory",
+    "version": "0.0.1",
+    "path": "skills/gh-issue-to-demand-signal"
+  },
   {
     "name": "google-trends-api-skills",
     "description": "SEO keyword research workflow for blog generation using Google Trends data.",

package/skills/gh-issue-to-demand-signal/.env.example

@@ -0,0 +1,3 @@
+GITHUB_TOKEN=      # optional -- github.com/settings/tokens (no scopes needed for public repos)
+                   # Without it: 60 req/hr unauthenticated (enough for ~2 fetches before hitting limit)
+                   # With it: 5000 req/hr (effectively unlimited for this skill's 2-page fetch pattern)

package/skills/gh-issue-to-demand-signal/README.md

@@ -0,0 +1,118 @@
+# gh-issue-to-demand-signal
+
+Give the skill a competitor's public GitHub repo URL. It fetches their open issues, filters noise locally, clusters into 6 demand categories using the AI already running the skill, scores by real engagement (reactions), detects ignored demand (high reactions + no response = your opportunity), and outputs a ranked demand gap report with a GTM messaging brief.
+
+## Install
+
+```bash
+npx "@opendirectory.dev/skills" install gh-issue-to-demand-signal --target claude
+```
+
+### Video Tutorial
+Watch this quick video to see how it's done:
+
+https://github.com/user-attachments/assets/ee98a1b5-ebc4-452f-bbfb-c434f2935067
+
+### Step 1: Download the skill from GitHub
+1. Click the **Code** button on this repo's GitHub page.
+2. Select **Download ZIP** to download the repository.
+3. Extract the ZIP file on your computer.
+
+### Step 2: Install the Skill in Claude
+1. Open your **Claude desktop app**.
+2. Go to the sidebar on the left side and click on the **Customize** section.
+3. Click on the **Skills** tab, then click on the **+** (plus) icon button to create a new skill.
+4. Choose the option to **Upload a skill**, and drag and drop the `.zip` file (or you can extract it and drop the folder, both work).
+
+> **Note:** For some skills (like `position-me`), the `SKILL.md` file might be located inside a subfolder. Always make sure you are uploading the specific folder that contains the `SKILL.md` file!
+
+## What It Does
+
+- Fetches up to 200 open issues from any public GitHub repo (no auth required)
+- Filters noise locally: removes PRs, bot issues, zero-engagement issues, and chore-pattern titles
+- Computes a demand score per issue: `(reactions["+1"] x 2) + (comments x 0.5)`
+- Detects "ignored demand": issues with 10+ reactions, open 6+ months, no planned label
+- Clusters issues into 6 categories using the AI running the skill (no external API key needed): feature gaps, bug patterns, UX complaints, performance issues, missing integrations, missing docs
+- Generates 5-8 cluster themes with total demand scores
+- Messaging brief: 3 positioning angles + 3 outreach hooks + cluster-specific headlines
+- Saves output to `docs/demand-signals/[owner]-[repo]-[date].md`
+
+## Requirements
+
+| Requirement | Purpose | How to Set Up |
+|---|---|---|
+| GitHub token | Raises rate limit from 60/hr to 5000/hr | github.com/settings/tokens (no scopes needed for public repos) |
+
+No external AI API key needed. The skill uses the AI assistant running it (Claude, Gemini, Copilot) to do the clustering and messaging brief. GitHub token is optional but recommended for repeated use.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Add GITHUB_TOKEN (optional, recommended for repeated use)
+```
+
+## How to Use
+
+```
+"Scan competitor GitHub issues: https://github.com/vercel/next.js"
+"What are users asking for in facebook/react?"
+"Find demand gaps in linear-app/linear"
+"Turn GitHub complaints into messaging: https://github.com/supabase/supabase"
+"What should I build based on competitor issues? vercel/next.js"
+"Which features are users begging for in this repo?"
+```
+
+## Why This Matters
+
+A busy product team cannot read 500 open issues. This skill does the work: ranks by real user demand (reaction counts), clusters into actionable GTM categories, detects ignored demand (where competitors have been silent the longest), and translates raw complaints into positioning language.
+
+**The demand score formula:** `(reactions["+1"] x 2) + (comments x 0.5)`. Reactions are weighted higher than comments because reactions are pure signal -- a thumbs-up means "I want this." Comments include maintainer responses, off-topic discussion, and spam.
+
+**Ignored demand is your opportunity:** An issue with 50 reactions that has been open for 2 years with no planned label means their users have been waiting. That is your product's first billboard.
+
+## The 6 Demand Categories
+
+| Category | What it captures |
+|---|---|
+| `feature_gap` | Functionality that does not exist yet |
+| `bug_pattern` | Recurring broken behavior that erodes trust |
+| `ux_complaint` | Friction, confusion, or workflow problems |
+| `performance` | Slowness, timeouts, resource usage |
+| `integration_missing` | Requests to connect with other tools or APIs |
+| `docs_missing` | Confusion caused by absent or wrong documentation |
+
+## Output
+
+Each run produces:
+
+1. **Demand Gap Leaderboard**: clusters ranked by total demand score
+2. **Ignored Demand section**: issues open 6+ months with 10+ reactions and no response
+3. **Top 10 Highest-Demand Issues**: verbatim titles, reaction counts, direct GitHub links
+4. **Cluster Deep Dives**: top 3 clusters with theme name, pain summary, top 3 verbatim issues
+5. **Messaging Brief**: 3 positioning angles citing exact demand evidence
+6. **GTM Angles**: 3 outreach hooks using verbatim issue language
+
+## Cost per Run
+
+- GitHub API: 2 calls -- free (unauthenticated: 60/hr limit, token: 5000/hr)
+- AI analysis: uses the model already running the skill -- no additional cost
+- Total: free
+
+## Project Structure
+
+```
+gh-issue-to-demand-signal/
+├── SKILL.md
+├── README.md
+├── .env.example
+├── evals/
+│   └── evals.json
+└── references/
+    ├── demand-categories.md
+    └── gtm-translation.md
+```
+
+## License
+
+MIT

package/skills/gh-issue-to-demand-signal/SKILL.md

@@ -0,0 +1,638 @@
+---
+name: gh-issue-to-demand-signal
+description: Takes a competitor's public GitHub repo URL, fetches their open issues via the GitHub REST API, filters noise locally, clusters issues into 6 demand categories, computes a demand score per issue and per cluster, and outputs a ranked demand gap report with a GTM messaging brief. Use when asked to scan a competitor's GitHub issues, find what their users are begging for, turn GitHub complaints into product positioning, identify competitor feature gaps, or generate messaging from real user demand. Trigger when a user says "scan competitor issues", "what are users asking for on X repo", "find demand gaps in Y", "turn GitHub issues into messaging", or "what should I build based on competitor complaints".
+compatibility: [claude-code, gemini-cli, github-copilot]
+---
+
+# GitHub Issue Demand Signal
+
+Take a competitor's public GitHub repo. Fetch their open issues. Filter noise locally. Cluster into 6 demand categories. Score by real engagement. Output a ranked demand gap report and GTM messaging brief.
+
+---
+
+**Critical rule:** Every issue title in the output must be verbatim from the GitHub API response. Every cluster theme name must be derived from actual issue titles in that cluster. If fewer than 10 issues remain after noise filtering, stop and tell the user -- the repo is too small for reliable clustering. No invented issue content anywhere.
+
+---
+
+## Common Mistakes
+
+| The agent will want to... | Why that's wrong |
+|---|---|
+| Send all 200 raw issues to the AI without filtering | Bot issues, PRs, and zero-engagement noise inflate cluster counts and waste context. Filter locally first. |
+| Use comment count as the primary demand signal | Comments include maintainer responses, off-topic discussion, and spam. reactions["+1"] is the cleanest buyer signal. |
+| Paraphrase issue titles when summarizing clusters | Paraphrasing loses the buyer's exact language, which is the entire point. Use verbatim issue titles. |
+| Continue past Step 4 if fewer than 10 issues remain after filtering | Under 10 issues means the repo is too small or the wrong URL was given. Clustering on sparse data produces meaningless categories. |
+| Include pull requests in the analysis | The GitHub Issues endpoint returns PRs too. Filter by checking that the pull_request key is absent on the issue object. |
+| Mark an issue as ignored demand without checking all 3 criteria | All three must be true: reactions >= 10, age >= 180 days, no planned/in-progress/roadmap label. Missing one criterion disqualifies the issue. |
+
+---
+
+## Step 1: Setup Check
+
+```bash
+echo "GITHUB_TOKEN: ${GITHUB_TOKEN:-not set, unauthenticated rate limit applies (60 req/hr)}"
+```
+
+**If GITHUB_TOKEN is not set:** Continue. Tell the user: "GITHUB_TOKEN is not set. Unauthenticated rate limit is 60 requests/hour -- enough for 2 fetches before hitting the limit. For repeated use, add a token at github.com/settings/tokens (no scopes needed for public repos)."
+
+---
+
+## Step 2: Gather Input
+
+You need:
+- GitHub repo URL (e.g. https://github.com/owner/repo) or owner/repo slug (e.g. facebook/react)
+
+Parse owner and repo from input:
+
+```bash
+python3 << 'PYEOF'
+import re, sys, os
+
+raw = "REPO_INPUT_HERE"
+
+# Normalize to owner/repo
+if raw.startswith("http"):
+    m = re.search(r"github\.com/([^/]+)/([^/?\s]+)", raw)
+    if not m:
+        print("ERROR: Could not parse GitHub URL. Expected format: https://github.com/owner/repo")
+        sys.exit(1)
+    owner, repo = m.group(1), m.group(2).rstrip("/")
+elif "/" in raw:
+    parts = raw.strip().split("/")
+    owner, repo = parts[0], parts[1]
+else:
+    print("ERROR: Input must be a GitHub URL or owner/repo slug (e.g. vercel/next.js)")
+    sys.exit(1)
+
+print(f"Owner: {owner}")
+print(f"Repo: {repo}")
+
+with open("/tmp/ghd-target.txt", "w") as f:
+    f.write(f"{owner}/{repo}")
+PYEOF
+```
+
+**If parsing fails:** Stop. Ask: "Please provide the GitHub repo as a URL (https://github.com/owner/repo) or an owner/repo slug (e.g. vercel/next.js)."
+
+---
+
+## Step 3: Fetch Issues from GitHub REST API
+
+Fetch up to 200 issues (2 pages of 100). Check rate limit after the first fetch.
+
+```bash
+python3 << 'PYEOF'
+import json, urllib.request, os, sys
+from datetime import datetime, timezone
+
+target = open("/tmp/ghd-target.txt").read().strip()
+owner_repo = target
+token = os.environ.get("GITHUB_TOKEN", "")
+
+headers = {"Accept": "application/vnd.github+json", "User-Agent": "gh-issue-demand-signal/1.0"}
+if token:
+    headers["Authorization"] = f"Bearer {token}"
+
+all_issues = []
+rate_limit_hit = False
+
+for page in [1, 2]:
+    url = f"https://api.github.com/repos/{owner_repo}/issues?state=open&per_page=100&page={page}"
+    req = urllib.request.Request(url, headers=headers)
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            # Check rate limit after first page
+            if page == 1:
+                remaining = int(resp.headers.get("X-RateLimit-Remaining", 999))
+                reset_ts = resp.headers.get("X-RateLimit-Reset", "")
+                if remaining == 0:
+                    reset_str = datetime.fromtimestamp(int(reset_ts), tz=timezone.utc).strftime("%H:%M UTC") if reset_ts else "unknown"
+                    print(f"ERROR: GitHub rate limit exhausted. Resets at {reset_str}.")
+                    print("Add GITHUB_TOKEN to your .env file to get 5000 req/hr. See github.com/settings/tokens (no scopes needed).")
+                    sys.exit(1)
+                print(f"Rate limit remaining: {remaining}")
+
+                # Check for 404/403
+                status = resp.status
+                if status == 404:
+                    print(f"ERROR: Repo '{owner_repo}' not found. Check the URL or slug.")
+                    sys.exit(1)
+
+            page_data = json.loads(resp.read())
+            if not page_data:
+                print(f"Page {page}: empty, stopping.")
+                break
+            all_issues.extend(page_data)
+            print(f"Page {page}: {len(page_data)} issues fetched")
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            print(f"ERROR: Repo '{owner_repo}' not found (404). Check the URL or slug.")
+        elif e.code == 403:
+            print(f"ERROR: Access denied (403). Repo may be private or rate limit hit.")
+        else:
+            print(f"ERROR: GitHub API returned HTTP {e.code}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"ERROR: Failed to fetch page {page}: {e}")
+        sys.exit(1)
+
+print(f"Total raw issues fetched: {len(all_issues)}")
+json.dump(all_issues, open("/tmp/ghd-raw-issues.json", "w"), indent=2)
+PYEOF
+```
+
+**If GitHub returns 404:** Stop. Tell the user: "Repo not found. Check the URL or slug and try again. Private repos are not accessible without authentication and explicit repo scope."
+
+**If GitHub returns 403 with rate limit header:** Stop. Show the reset time and tell the user to add GITHUB_TOKEN.
+
+---
+
+## Step 4: Pre-Process Locally -- Filter, Score, Detect Ignored Demand
+
+No API call. Pure Python. Run before anything goes to the AI.
+
+```bash
+python3 << 'PYEOF'
+import json, re
+from datetime import datetime, timezone
+
+raw = json.load(open("/tmp/ghd-raw-issues.json"))
+target = open("/tmp/ghd-target.txt").read().strip()
+now = datetime.now(tz=timezone.utc)
+
+noise_patterns = re.compile(
+    r"^(chore|deps|bump|renovate|dependabot|release|ci|build|revert)[\s:\[]",
+    re.IGNORECASE
+)
+pr_title_patterns = re.compile(
+    r"^(feat|fix|refactor|docs|test|style|perf|chore)(\(.+\))?:",
+    re.IGNORECASE
+)
+
+filtered = []
+noise_count = 0
+noise_reasons = {}
+
+for issue in raw:
+    # Skip pull requests (GitHub Issues endpoint returns PRs too)
+    if "pull_request" in issue:
+        noise_count += 1
+        noise_reasons["pull_request"] = noise_reasons.get("pull_request", 0) + 1
+        continue
+
+    title = issue.get("title", "")
+    reactions = issue.get("reactions", {}).get("+1", 0)
+    comments = issue.get("comments", 0)
+    user_type = (issue.get("user") or {}).get("type", "User")
+
+    # Skip bot-authored issues
+    if user_type == "Bot":
+        noise_count += 1
+        noise_reasons["bot_author"] = noise_reasons.get("bot_author", 0) + 1
+        continue
+
+    # Skip bot-pattern titles
+    if noise_patterns.match(title):
+        noise_count += 1
+        noise_reasons["bot_title"] = noise_reasons.get("bot_title", 0) + 1
+        continue
+
+    # Skip PR-as-issue titles
+    if pr_title_patterns.match(title):
+        noise_count += 1
+        noise_reasons["pr_as_issue"] = noise_reasons.get("pr_as_issue", 0) + 1
+        continue
+
+    # Skip zero-signal issues
+    if reactions == 0 and comments == 0:
+        noise_count += 1
+        noise_reasons["zero_signal"] = noise_reasons.get("zero_signal", 0) + 1
+        continue
+
+    # Compute demand score
+    demand_score = (reactions * 2) + (comments * 0.5)
+
+    # Detect ignored demand
+    created_at = issue.get("created_at", "")
+    if created_at:
+        created = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+        age_days = (now - created).days
+    else:
+        age_days = 0
+
+    labels = [l.get("name", "").lower() for l in issue.get("labels", [])]
+    has_planned_label = any(
+        kw in label for label in labels
+        for kw in ["in-progress", "planned", "roadmap", "wip", "in progress"]
+    )
+
+    ignored_demand = (
+        reactions >= 10 and
+        age_days >= 180 and
+        not has_planned_label
+    )
+
+    filtered.append({
+        "number": issue["number"],
+        "title": title,
+        "url": issue.get("html_url", f"https://github.com/{target}/issues/{issue['number']}"),
+        "reactions_plus1": reactions,
+        "comments": comments,
+        "demand_score": demand_score,
+        "age_days": age_days,
+        "labels": labels,
+        "ignored_demand": ignored_demand,
+        "body_snippet": (issue.get("body") or "")[:300]
+    })
+
+# Sort by demand score descending
+filtered.sort(key=lambda x: x["demand_score"], reverse=True)
+
+print(f"Raw issues: {len(raw)}")
+print(f"Noise filtered: {noise_count} ({', '.join(f'{k}: {v}' for k, v in noise_reasons.items())})")
+print(f"Issues for analysis: {len(filtered)}")
+
+if len(filtered) < 10:
+    print(f"ERROR: Only {len(filtered)} issues remain after filtering. This repo has too few engaged issues for reliable clustering.")
+    print("Try a larger repo or a repo with more community engagement.")
+    import sys; sys.exit(1)
+
+# Ignored demand summary
+ignored = [i for i in filtered if i["ignored_demand"]]
+print(f"Ignored demand issues: {len(ignored)}")
+
+json.dump(filtered, open("/tmp/ghd-filtered-issues.json", "w"), indent=2)
+print("Pre-processing complete.")
+PYEOF
+```
+
+**If fewer than 10 issues remain after filtering:** Stop. Tell the user exactly how many issues were found and filtered, and why the repo is too small for reliable demand clustering.
+
+---
+
+## Step 5: Cluster Issues
+
+Print the filtered issues for analysis:
+
+```bash
+python3 << 'PYEOF'
+import json
+filtered = json.load(open("/tmp/ghd-filtered-issues.json"))
+target = open("/tmp/ghd-target.txt").read().strip()
+
+issue_list = filtered[:150]
+print(f"Repo: {target}")
+print(f"Issues to cluster: {len(issue_list)}")
+print()
+for i in issue_list:
+    labels_str = f" [{', '.join(i['labels'][:3])}]" if i['labels'] else ""
+    print(f"#{i['number']} [score:{round(i['demand_score'],1)} reactions:{i['reactions_plus1']}] {i['title']}{labels_str}")
+PYEOF
+```
+
+Classify each issue printed above into one of these 6 categories:
+`feature_gap`, `bug_pattern`, `ux_complaint`, `performance`, `integration_missing`, `docs_missing`
+
+Rules:
+- Classify each issue into exactly one category
+- Extract a 1-sentence pain statement using the user's exact language from the title -- do not paraphrase
+- Identify 5-8 cluster themes: short phrases (3-6 words) capturing dominant complaint patterns across all issues
+- No em dashes. No marketing language.
+
+Write your analysis to `/tmp/ghd-clusters.json` with this exact structure:
+
+```json
+{
+  "classified_issues": [
+    {"number": 123, "category": "feature_gap", "pain_statement": "Users need X which does not exist yet"}
+  ],
+  "cluster_themes": [
+    {"theme_name": "Missing export options", "category": "feature_gap", "issue_numbers": [123, 456, 789]}
+  ],
+  "category_counts": {"feature_gap": 5, "bug_pattern": 3, "ux_complaint": 4, "performance": 2, "integration_missing": 6, "docs_missing": 1}
+}
+```
+
+After writing the file, confirm with:
+
+```bash
+python3 -c "
+import json
+d = json.load(open('/tmp/ghd-clusters.json'))
+print(f'Classified: {len(d[\"classified_issues\"])} issues, {len(d[\"cluster_themes\"])} themes')
+print('Categories:', d['category_counts'])
+"
+```
+
+---
+
+## Step 6: Messaging Brief
+
+Compute total demand score per cluster and print the top 3:
+
+```bash
+python3 << 'PYEOF'
+import json
+
+filtered = json.load(open("/tmp/ghd-filtered-issues.json"))
+clusters = json.load(open("/tmp/ghd-clusters.json"))
+target = open("/tmp/ghd-target.txt").read().strip()
+
+demand_by_issue = {i["number"]: i["demand_score"] for i in filtered}
+issue_titles = {i["number"]: i["title"] for i in filtered}
+issue_reactions = {i["number"]: i["reactions_plus1"] for i in filtered}
+
+enriched_themes = []
+for theme in clusters.get("cluster_themes", []):
+    issue_nums = theme.get("issue_numbers", [])
+    total_demand = sum(demand_by_issue.get(n, 0) for n in issue_nums)
+    top_issues = sorted(issue_nums, key=lambda n: demand_by_issue.get(n, 0), reverse=True)[:3]
+    enriched_themes.append({
+        "theme_name": theme["theme_name"],
+        "category": theme["category"],
+        "issue_count": len(issue_nums),
+        "total_demand_score": round(total_demand, 1),
+        "top_issues": [
+            {"number": n, "title": issue_titles.get(n, ""), "reactions": issue_reactions.get(n, 0)}
+            for n in top_issues
+        ]
+    })
+
+enriched_themes.sort(key=lambda x: x["total_demand_score"], reverse=True)
+json.dump(enriched_themes, open("/tmp/ghd-enriched-themes.json", "w"), indent=2)
+
+print(f"Top 3 clusters for messaging brief (repo: {target}):")
+for t in enriched_themes[:3]:
+    print(f"\n  {t['theme_name']} ({t['category']}) -- total demand: {t['total_demand_score']}")
+    for ti in t["top_issues"]:
+        print(f"    #{ti['number']}: \"{ti['title']}\" ({ti['reactions']} reactions)")
+PYEOF
+```
+
+Generate a GTM messaging brief from the top 3 clusters printed above.
+
+Rules:
+- Each positioning angle must cite the specific cluster it comes from
+- Each outreach hook must quote a verbatim issue title in quotation marks
+- Headlines must include a number or specific named pain -- no generic statements
+- No em dashes. No forbidden words: powerful, robust, seamless, innovative, game-changing, streamline, leverage, transform
+
+Write your brief to `/tmp/ghd-brief.json` with this exact structure:
+
+```json
+{
+  "positioning_angles": [
+    {
+      "angle_name": "3-5 word label",
+      "cluster_source": "theme_name from cluster",
+      "positioning_statement": "2-3 sentences on what your product does that this competitor does not",
+      "evidence": "verbatim issue title that best illustrates this gap"
+    }
+  ],
+  "outreach_hooks": [
+    {
+      "hook_type": "pain quote hook",
+      "hook_text": "2-3 sentences quoting a verbatim issue title in quotes",
+      "best_for": "audience this hook works for"
+    }
+  ],
+  "cluster_headlines": [
+    {
+      "theme_name": "from the cluster",
+      "headline": "specific headline with a number or named pain",
+      "sub_copy": "1 sentence expanding the headline"
+    }
+  ]
+}
+```
+
+After writing the file, confirm with:
+
+```bash
+python3 -c "
+import json
+d = json.load(open('/tmp/ghd-brief.json'))
+print('Positioning angles:', len(d.get('positioning_angles', [])))
+print('Outreach hooks:', len(d.get('outreach_hooks', [])))
+print('Cluster headlines:', len(d.get('cluster_headlines', [])))
+"
+```
+
+---
+
+## Step 7: Self-QA
+
+Run before presenting. Verify evidence. Remove violations. Check output integrity.
+
+```bash
+python3 << 'PYEOF'
+import json
+
+filtered = json.load(open("/tmp/ghd-filtered-issues.json"))
+clusters = json.load(open("/tmp/ghd-clusters.json"))
+themes = json.load(open("/tmp/ghd-enriched-themes.json"))
+brief = json.load(open("/tmp/ghd-brief.json"))
+target = open("/tmp/ghd-target.txt").read().strip()
+
+failures = []
+real_titles = {i["number"]: i["title"] for i in filtered}
+
+# Verify: classified_issues only reference real issue numbers
+real_numbers = set(real_titles.keys())
+hallucinated = [
+    c["number"] for c in clusters.get("classified_issues", [])
+    if c["number"] not in real_numbers
+]
+if hallucinated:
+    failures.append(f"Removed {len(hallucinated)} hallucinated issue numbers from classified_issues: {hallucinated[:5]}")
+    clusters["classified_issues"] = [
+        c for c in clusters.get("classified_issues", [])
+        if c["number"] in real_numbers
+    ]
+
+# Verify: top-10 list is sorted by demand_score descending
+top10 = filtered[:10]
+for i, issue in enumerate(top10):
+    if i > 0 and issue["demand_score"] > top10[i-1]["demand_score"]:
+        failures.append("Top-10 list was not sorted by demand_score -- re-sorted.")
+        filtered.sort(key=lambda x: x["demand_score"], reverse=True)
+        top10 = filtered[:10]
+        break
+
+# Verify: ignored demand issues meet all 3 criteria
+ignored = [i for i in filtered if i["ignored_demand"]]
+for issue in ignored:
+    if issue["reactions_plus1"] < 10 or issue["age_days"] < 180:
+        issue["ignored_demand"] = False
+        failures.append(f"Removed issue #{issue['number']} from ignored demand -- did not meet all 3 criteria")
+
+# Check messaging brief counts
+if len(brief.get("positioning_angles", [])) != 3:
+    failures.append(f"Expected 3 positioning angles, got {len(brief.get('positioning_angles', []))}")
+if len(brief.get("outreach_hooks", [])) != 3:
+    failures.append(f"Expected 3 outreach hooks, got {len(brief.get('outreach_hooks', []))}")
+if len(brief.get("cluster_headlines", [])) != 3:
+    failures.append(f"Expected 3 cluster headlines, got {len(brief.get('cluster_headlines', []))}")
+
+# Check for em dashes in brief
+brief_str = json.dumps(brief)
+if "\u2014" in brief_str:
+    brief_str = brief_str.replace("\u2014", " - ")
+    brief = json.loads(brief_str)
+    failures.append("Fixed: em dash characters removed from messaging brief")
+
+# Check for forbidden words
+forbidden = ["powerful", "robust", "seamless", "innovative", "game-changing", "streamline", "leverage", "transform"]
+full_text = (json.dumps(clusters) + json.dumps(brief)).lower()
+for word in forbidden:
+    if word in full_text:
+        failures.append(f"Warning: forbidden word '{word}' found in output -- review before presenting")
+
+# Build final output bundle
+output = {
+    "repo": target,
+    "issues_analyzed": len(filtered),
+    "clusters": clusters,
+    "enriched_themes": themes,
+    "filtered_issues": filtered,
+    "messaging_brief": brief,
+    "data_quality_flags": failures
+}
+
+json.dump(output, open("/tmp/ghd-output.json", "w"), indent=2)
+print(f"QA complete. Issues addressed: {len(failures)}")
+for f in failures:
+    print(f"  - {f}")
+if not failures:
+    print("All QA checks passed.")
+PYEOF
+```
+
+---
+
+## Step 8: Save and Present Output
+
+```bash
+python3 << 'PYEOF'
+import json
+from datetime import datetime, timezone
+
+output = json.load(open("/tmp/ghd-output.json"))
+target = output["repo"]
+repo_slug = target.replace("/", "-")
+date_str = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d")
+
+filtered = output["filtered_issues"]
+themes = output["enriched_themes"]
+clusters = output["clusters"]
+brief = output["messaging_brief"]
+flags = output["data_quality_flags"]
+
+ignored = [i for i in filtered if i.get("ignored_demand")]
+top10 = filtered[:10]
+
+# Build category summary from cluster data
+category_counts = clusters.get("category_counts", {})
+
+lines = [
+    f"## Demand Gap Report: {target}",
+    f"Issues analyzed: {output['issues_analyzed']} | Date: {date_str}",
+    "",
+    "---",
+    "",
+    "### Demand Gap Leaderboard",
+    "",
+    "| Rank | Theme | Category | Issues | Total Demand Score | Top Issue Reactions |",
+    "|---|---|---|---|---|---|",
+]
+
+for i, theme in enumerate(themes[:8], 1):
+    top_reactions = theme["top_issues"][0]["reactions"] if theme["top_issues"] else 0
+    lines.append(
+        f"| {i} | {theme['theme_name']} | {theme['category']} | "
+        f"{theme['issue_count']} | {theme['total_demand_score']} | {top_reactions} |"
+    )
+
+lines += ["", "---", ""]
+
+if ignored:
+    lines += [
+        "### Ignored Demand (High Reactions, No Maintainer Response)",
+        "",
+        "These issues have 10+ reactions, are 6+ months old, and have no planned/in-progress label.",
+        "This is your opportunity window.",
+        "",
+    ]
+    for issue in ignored[:10]:
+        lines.append(
+            f"- [{issue['title']}]({issue['url']}) -- "
+            f"{issue['reactions_plus1']} reactions, {issue['age_days']} days old"
+        )
+    lines += ["", "---", ""]
+
+lines += [
+    "### Top 10 Highest-Demand Issues",
+    "",
+    "| Rank | Issue | Reactions | Comments | Demand Score | Link |",
+    "|---|---|---|---|---|---|",
+]
+for i, issue in enumerate(top10, 1):
+    short_title = issue["title"][:70] + ("..." if len(issue["title"]) > 70 else "")
+    lines.append(
+        f"| {i} | {short_title} | {issue['reactions_plus1']} | "
+        f"{issue['comments']} | {round(issue['demand_score'], 1)} | "
+        f"[#{issue['number']}]({issue['url']}) |"
+    )
+
+lines += ["", "---", "", "### Cluster Deep Dives", ""]
+
+for theme in themes[:3]:
+    lines.append(f"#### {theme['theme_name']}")
+    lines.append(f"Category: {theme['category']} | Issues: {theme['issue_count']} | Total demand score: {theme['total_demand_score']}")
+    lines.append("")
+    lines.append("Top issues in this cluster:")
+    for ti in theme["top_issues"]:
+        lines.append(f"- \"{ti['title']}\" -- {ti['reactions']} reactions")
+    lines.append("")
+
+lines += ["---", "", "### Messaging Brief", ""]
+
+for angle in brief.get("positioning_angles", []):
+    lines.append(f"**{angle.get('angle_name', 'Angle')}**")
+    lines.append(angle.get("positioning_statement", ""))
+    lines.append(f"Evidence: \"{angle.get('evidence', '')}\"")
+    lines.append("")
+
+lines += ["---", "", "### GTM Angles", ""]
+
+for hook in brief.get("outreach_hooks", []):
+    lines.append(f"**{hook.get('hook_type', 'Hook')}**")
+    lines.append(hook.get("hook_text", ""))
+    lines.append(f"Best for: {hook.get('best_for', '')}")
+    lines.append("")
+
+lines += ["---", ""]
+if flags:
+    lines.append(f"Data quality notes: {'; '.join(flags)}")
+else:
+    lines.append("Data quality notes: None")
+
+output_path = f"docs/demand-signals/{repo_slug}-{date_str}.md"
+import os
+os.makedirs("docs/demand-signals", exist_ok=True)
+open(output_path, "w").write("\n".join(lines))
+print(f"Saved to: {output_path}")
+
+# Print to console
+print("\n" + "\n".join(lines))
+PYEOF
+```
+
+Clean up temp files:
+
+```bash
+rm -f /tmp/ghd-target.txt /tmp/ghd-raw-issues.json /tmp/ghd-filtered-issues.json \
+      /tmp/ghd-cluster-request.json /tmp/ghd-clusters.json /tmp/ghd-enriched-themes.json \
+      /tmp/ghd-brief-request.json /tmp/ghd-brief.json /tmp/ghd-output.json
+```

package/skills/gh-issue-to-demand-signal/evals/evals.json

@@ -0,0 +1,118 @@
+[
+  {
+    "id": "eval_001",
+    "name": "Popular OSS repo: full pipeline with 100+ issues, all 6 categories populated",
+    "description": "A large, active public repo with hundreds of open issues. Validates the full 8-step workflow, noise filtering, demand scoring, all 6 categories appearing in output, and correct sorting.",
+    "input": {
+      "prompt": "Scan competitor GitHub issues: https://github.com/facebook/react",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Parses owner=facebook, repo=react correctly",
+      "Fetches 2 pages of issues from GitHub REST API",
+      "Checks X-RateLimit-Remaining after first page fetch",
+      "Filters out pull requests (pull_request key present), bot-authored issues, chore/deps/bump title patterns, zero-reaction + zero-comment issues",
+      "Issue count after filtering is above 10 -- proceeds to clustering",
+      "demand_score computed as (reactions_plus1 * 2) + (comments * 0.5) for each issue",
+      "ignored_demand field set to true only for issues with reactions >= 10, age_days >= 180, and no planned label",
+      "Skill prints filtered issues and asks the AI to classify them into 6 categories",
+      "AI writes /tmp/ghd-clusters.json with classified_issues, cluster_themes, and category_counts",
+      "All 6 categories appear in category_counts",
+      "Top-10 list sorted by demand_score descending",
+      "Skill prints top 3 clusters and asks the AI to write a messaging brief",
+      "AI writes /tmp/ghd-brief.json with exactly 3 positioning_angles, 3 outreach_hooks, 3 cluster_headlines",
+      "Every outreach hook contains a quoted verbatim issue title",
+      "Output saved to docs/demand-signals/facebook-react-[date].md",
+      "No em dashes in any output section"
+    ],
+    "expected_output": "Full demand gap report with leaderboard, ignored demand section, top-10, cluster deep dives, messaging brief, and GTM angles"
+  },
+  {
+    "id": "eval_002",
+    "name": "Small or inactive repo: graceful stop after Step 4",
+    "description": "A repo with very few open issues or a niche project where most issues have zero reactions. After noise filtering, fewer than 10 issues remain. Validates graceful stop with a clear explanation.",
+    "input": {
+      "prompt": "Analyze issues in this repo: https://github.com/nicowillis/tiny-test-repo",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Fetches issues successfully",
+      "Noise filter removes most issues (zero engagement, bot patterns, etc.)",
+      "After filtering, fewer than 10 issues remain",
+      "Stops at Step 4 -- does NOT proceed to clustering",
+      "Tells the user exactly how many issues were found and how many were filtered",
+      "Explains why fewer than 10 issues is insufficient for reliable clustering",
+      "Suggests trying a larger or more community-engaged repo",
+      "No partial output generated"
+    ],
+    "expected_output": "Graceful stop message with issue counts, noise breakdown, and suggestion to try a different repo"
+  },
+  {
+    "id": "eval_003",
+    "name": "Private or non-existent repo: stops at Step 3 with exact error",
+    "description": "User provides a URL for a repo that either does not exist (404) or is private (403). Validates that the skill stops at Step 3 with a clear, actionable error message.",
+    "input": {
+      "prompt": "Find demand gaps in https://github.com/nonexistent-org/nonexistent-repo-xyz",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Parses owner/repo from URL",
+      "Attempts GitHub API fetch",
+      "GitHub returns 404",
+      "Stops immediately at Step 3",
+      "Tells the user: 'Repo not found. Check the URL or slug and try again. Private repos are not accessible without authentication and explicit repo scope.'",
+      "Does NOT attempt noise filtering",
+      "Does NOT proceed to clustering"
+    ],
+    "expected_output": "Immediate stop at Step 3 with 404 error message. No partial analysis generated."
+  },
+  {
+    "id": "eval_004",
+    "name": "owner/repo slug input (no full URL): parses correctly and runs full pipeline",
+    "description": "User provides an owner/repo slug instead of a full GitHub URL (e.g. 'vercel/next.js' instead of 'https://github.com/vercel/next.js'). Validates that the slug parsing path works correctly.",
+    "input": {
+      "prompt": "What are users asking for in vercel/next.js?",
+      "env": {
+        "GITHUB_TOKEN": "set"
+      }
+    },
+    "expected_behavior": [
+      "Step 2 detects no 'github.com' URL in the input",
+      "Falls into the owner/repo slug parsing path",
+      "Correctly splits 'vercel/next.js' into owner=vercel, repo=next.js",
+      "Writes 'vercel/next.js' to /tmp/ghd-target.txt",
+      "Step 3 fetches from https://api.github.com/repos/vercel/next.js/issues successfully",
+      "Full pipeline runs to completion",
+      "Output filename uses 'vercel-next.js' as the repo slug",
+      "No error about invalid URL format"
+    ],
+    "expected_output": "Full demand gap report identical in format to a full URL run. Slug parsing is transparent to the output."
+  },
+  {
+    "id": "eval_005",
+    "name": "No GITHUB_TOKEN, rate limit hit: stops with reset time and token instructions",
+    "description": "User has no GITHUB_TOKEN and has already hit the 60/hr unauthenticated rate limit. Validates that the skill detects the rate limit header and stops with the reset time and token setup instructions.",
+    "input": {
+      "prompt": "What are users asking for in facebook/react?",
+      "env": {
+        "GITHUB_TOKEN": "not set"
+      }
+    },
+    "expected_behavior": [
+      "Step 1 notes GITHUB_TOKEN is not set and warns about 60 req/hr limit",
+      "Step 3 attempts GitHub API fetch without token",
+      "GitHub API returns X-RateLimit-Remaining: 0 header",
+      "Skill detects the header value after the first page fetch",
+      "Stops immediately with message: exact reset time (converted from X-RateLimit-Reset timestamp) and instructions to add GITHUB_TOKEN at github.com/settings/tokens",
+      "Does NOT attempt page 2 fetch",
+      "Does NOT proceed to noise filtering or clustering"
+    ],
+    "expected_output": "Stop at Step 3 with rate limit message, reset time, and GitHub token setup link. No analysis generated."
+  }
+]

package/skills/gh-issue-to-demand-signal/references/demand-categories.md

@@ -0,0 +1,181 @@
+# Demand Categories Reference
+
+Used by SKILL.md Step 5 to guide AI classification of GitHub issues into one of 6 demand categories.
+
+---
+
+## The 6 Categories
+
+### feature_gap
+
+**What it captures:** Functionality the product does not have yet. User is describing something they want to do that is currently impossible.
+
+**Signal phrases:**
+- "add support for..."
+- "it would be great if..."
+- "please add..."
+- "feature request:"
+- "allow users to..."
+- "I wish I could..."
+- "would love to see..."
+
+**Examples:**
+- "Add support for keyboard shortcuts in the editor"
+- "Allow exporting to PDF format"
+- "Feature request: dark mode"
+- "Support for multiple workspaces per account"
+
+**Scoring note:** feature_gap issues with 20+ reactions represent product roadmap signals. These are the gaps your product can claim as intentional design choices.
+
+---
+
+### bug_pattern
+
+**What it captures:** Recurring broken behavior that erodes user trust. Distinct from a one-off error -- the word "pattern" matters. Multiple issues with similar titles indicate a systemic problem.
+
+**Signal phrases:**
+- "broken when..."
+- "not working..."
+- "fails to..."
+- "error when..."
+- "crashes if..."
+- "regression in..."
+- "breaks after..."
+
+**Examples:**
+- "Login fails when using SSO with Google"
+- "File upload crashes on files over 10MB"
+- "Pagination breaks on mobile"
+- "Notifications not sending after the latest update"
+
+**Scoring note:** Bug patterns with high reactions signal trust erosion. If a competitor has 5+ high-reaction bug issues in the same functional area, that area is a liability in their product positioning.
+
+---
+
+### ux_complaint
+
+**What it captures:** Friction, confusion, or workflow problems. The feature exists but it is hard to use, hard to find, or does not match how users actually work.
+
+**Signal phrases:**
+- "confusing..."
+- "hard to..."
+- "unclear how to..."
+- "should be easier to..."
+- "the UI for X is..."
+- "annoying that..."
+- "clunky..."
+- "why does X require..."
+
+**Examples:**
+- "Confusing navigation between projects"
+- "Hard to find the settings for notifications"
+- "Should be easier to bulk-edit items"
+- "The import flow has too many steps"
+
+**Scoring note:** UX complaints are positioning gold. "Confusing to use" is a contrast you can own directly. If their users are calling something confusing, your messaging can address that exact friction without naming the competitor.
+
+---
+
+### performance
+
+**What it captures:** Slowness, timeouts, resource usage, or reliability problems that degrade the experience even when the feature works correctly.
+
+**Signal phrases:**
+- "slow..."
+- "timeout..."
+- "takes too long..."
+- "high memory usage..."
+- "performance regression..."
+- "loading forever..."
+- "lags when..."
+- "CPU usage..."
+
+**Examples:**
+- "Search is slow on repos with 1000+ files"
+- "Dashboard takes 10+ seconds to load"
+- "Memory usage spikes when processing large files"
+- "Build times increased 3x after v2.0"
+
+**Scoring note:** Performance issues cluster by data size or scale. If the complaints mention large repos, large teams, or high-volume usage, the competitor has a scale ceiling. That ceiling is your advantage if you have solved it.
+
+---
+
+### integration_missing
+
+**What it captures:** Requests to connect with other tools, APIs, or platforms. Users want the product to work alongside something else in their stack.
+
+**Signal phrases:**
+- "integrate with..."
+- "support for [tool name]..."
+- "webhook..."
+- "API for..."
+- "connect to..."
+- "import from..."
+- "sync with..."
+- "plugin for..."
+
+**Examples:**
+- "Integrate with Slack for notifications"
+- "Support GitHub Actions webhook triggers"
+- "Add Zapier integration"
+- "Import from Notion"
+- "VS Code extension"
+
+**Scoring note:** Integration requests cluster around the tools their users already use. A high-reaction integration request tells you where their users spend the rest of their day. If you already have that integration, it is a direct switch argument.
+
+---
+
+### docs_missing
+
+**What it captures:** Confusion caused by absent, incomplete, or incorrect documentation. The product may work correctly, but users cannot figure out how to use it.
+
+**Signal phrases:**
+- "no documentation for..."
+- "docs are missing..."
+- "unclear how to..."
+- "example for..."
+- "how do I..."
+- "docs don't explain..."
+- "add docs for..."
+- "tutorial for..."
+
+**Examples:**
+- "No documentation for the webhook authentication flow"
+- "Missing example for advanced configuration"
+- "How do I set up custom domains? Docs don't cover this."
+- "Add a tutorial for migrating from v1 to v2"
+
+**Scoring note:** docs_missing issues often indicate a product that has grown faster than its documentation. High-reaction docs issues in a specific area indicate that the area is both important to users and opaque in practice.
+
+---
+
+## Classification Rules
+
+### One category per issue
+Every issue gets exactly one category. Use the primary pain, not all possible interpretations.
+
+- "The export feature is broken and also slow" -- classify as `bug_pattern` (primary pain: it does not work)
+- "Export to PDF is slow" -- classify as `performance` (it works, it is just slow)
+- "Add export to PDF" -- classify as `feature_gap` (it does not exist)
+
+### When to use ux_complaint vs docs_missing
+- If the user says "I can't figure out how to X" and the docs don't cover it: `docs_missing`
+- If the user says "X is confusing" or "X is hard to use" and the feature exists: `ux_complaint`
+- If both apply: `ux_complaint` (the UI is the product, the docs are secondary)
+
+### When to use bug_pattern vs performance
+- If it does not work at all: `bug_pattern`
+- If it works but is slow or resource-heavy: `performance`
+
+---
+
+## Category Demand Signal Interpretation
+
+| Category | What high demand here tells you |
+|---|---|
+| feature_gap | Their roadmap is behind their users. Name what you have built. |
+| bug_pattern | Trust erosion in a specific area. Position your reliability there. |
+| ux_complaint | Their users are struggling. Position your simplicity there. |
+| performance | They hit a scale ceiling. Position your throughput or response time. |
+| integration_missing | Their users live in a different stack. Show your integration depth. |
+| docs_missing | They ship but do not explain. Position your onboarding and support. |

package/skills/gh-issue-to-demand-signal/references/gtm-translation.md

@@ -0,0 +1,211 @@
+# GTM Translation Reference
+
+How to convert demand clusters from competitor GitHub issues into GTM language. Used by SKILL.md Step 6 to guide the messaging brief generation.
+
+---
+
+## The Translation Problem
+
+Raw demand data from GitHub is in user language, not buyer language. A product manager reads:
+
+> "Add support for multiple workspaces per account" -- 87 reactions, open 2 years
+
+A GTM-trained analyst reads:
+
+> "Enterprise buyers need multi-tenancy. This competitor has not shipped it in 2 years. 87 teams are waiting. If you have this, lead with it."
+
+This reference document is the bridge between those two readings.
+
+---
+
+## Translation by Category
+
+### feature_gap clusters
+
+**What the data shows:** Users want something that does not exist.
+
+**GTM translation:**
+- If you have the feature: "We built what [competitor] has not." Name the feature specifically.
+- If you are building it: Use the cluster as proof that the market exists. "87 teams on [competitor] asked for X. We built it."
+- If you do not have it: This is a roadmap signal, not a positioning signal yet.
+
+**Outreach hook pattern:**
+```
+"[Number] teams on [competitor] have been asking for [specific feature] for [time].
+We shipped [your feature] in [your product] [time ago / as a core feature].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Over 200 teams on [competitor] asked for multi-workspace support. It has been open for 3 years with no planned label.
+We built workspace isolation as a core feature, not an add-on.
+Would a 20-minute call be useful?"
+```
+
+---
+
+### bug_pattern clusters
+
+**What the data shows:** Something is reliably broken. High reaction counts on bug issues mean many users hit the same wall.
+
+**GTM translation:**
+- Do not say "they are buggy." Say: "Teams in [X workflow] need reliability."
+- Position the broken area as a category where you have invested specifically.
+- The number of reactions is the credibility anchor. Use it.
+
+**Outreach hook pattern:**
+```
+"[Number] teams using [competitor] hit [specific bug area].
+[Your product] was built [for/around/specifically to handle] this workflow without [the failure mode].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Teams using [competitor] have hit login failures with SSO -- 43 reactions on that issue, open for 18 months.
+We built our auth layer around SSO-first design and have not had an SSO outage in 18 months of production.
+Worth a conversation?"
+```
+
+---
+
+### ux_complaint clusters
+
+**What the data shows:** The feature exists but users cannot use it without friction.
+
+**GTM translation:**
+- Simplicity is a product decision, not a feature. Position it as intentional design.
+- Use "setup time" or "time to value" as the measurable proxy for simplicity.
+- Do not say "our UI is better." Say: "Teams get to [outcome] in [time], without [the friction they described]."
+
+**Outreach hook pattern:**
+```
+"[Number] users of [competitor] said [specific UX friction in quotes].
+[Your product] gets [persona] to [outcome] in [time] with [fewer steps / no setup / no configuration].
+[One-line ask]."
+```
+
+**Example:**
+```
+"158 users of [competitor] called the project navigation 'confusing' -- that issue is 2 years old.
+We redesigned navigation around the workflow, not the feature tree. Teams reach their first result in under 2 minutes.
+Would you like to see it?"
+```
+
+---
+
+### performance clusters
+
+**What the data shows:** The product hits a scale ceiling. High-reaction performance issues cluster around a specific bottleneck (large files, large teams, high query volume).
+
+**GTM translation:**
+- Name the scale ceiling specifically: "repos over 1000 files", "teams over 50 users", "queries over 10k/day".
+- If you have benchmarks, use them. If not, use the absence of the complaint as proof.
+- Performance positioning works best for technical buyers (engineers, infrastructure teams).
+
+**Outreach hook pattern:**
+```
+"Teams at [competitor] hit [specific bottleneck] at [scale threshold].
+[Your product] handles [scale threshold] in [benchmark or time].
+[One-line ask]."
+```
+
+**Example:**
+```
+"Engineering teams using [competitor] report 10+ second load times on repos over 500 files -- 67 reactions, no fix in sight.
+We load repos of that size in under 1.5 seconds because we index differently.
+I can show you a benchmark on a repo your size."
+```
+
+---
+
+### integration_missing clusters
+
+**What the data shows:** Users work in tools this competitor does not connect to. High-reaction integration requests tell you exactly what else is in their users' daily stack.
+
+**GTM translation:**
+- If you have the integration: make it the lead, not a footnote.
+- The reaction count is the size of the audience that wants this bridge. Name the number.
+- Integration positioning works best when the target tool is a category leader (Slack, Notion, GitHub Actions, Salesforce).
+
+**Outreach hook pattern:**
+```
+"[Number] teams on [competitor] asked for [specific integration]. It has been open [time] with no planned label.
+[Your product] connects to [integration] natively -- [brief description of how it works].
+[One-line ask]."
+```
+
+**Example:**
+```
+"94 teams on [competitor] asked for Slack integration. The request is 3 years old with no planned label.
+We shipped bidirectional Slack sync 6 months ago -- alerts in Slack, actions back to [your product].
+Worth showing you?"
+```
+
+---
+
+### docs_missing clusters
+
+**What the data shows:** Users cannot figure out how to do something. The product may work, but the path to value is opaque.
+
+**GTM translation:**
+- Documentation is a trust signal, not a feature. "We have clear docs" is not a hook.
+- Translate to: "Teams are in production in [time]" or "We have a guided setup for [exact use case they documented badly]."
+- Onboarding speed is the business outcome. Use it.
+
+**Outreach hook pattern:**
+```
+"[Number] users on [competitor] asked for documentation on [specific topic].
+We have [specific guide / template / interactive tutorial] for [exact use case].
+Teams using our [guide/setup] are in production in [time].
+[One-line ask]."
+```
+
+**Example:**
+```
+"38 teams on [competitor] asked for documentation on webhook authentication. There is still no official guide.
+We have a step-by-step webhook setup guide that gets teams from zero to first event in under 15 minutes.
+I can send it -- it works for any webhook destination, not just ours."
+```
+
+---
+
+## Using Verbatim Issue Language
+
+The most effective outreach hooks use the user's exact words from the issue title. This works because:
+
+1. It proves you read real feedback, not marketing copy.
+2. It speaks in the buyer's language, not product language.
+3. It names the pain before pitching the solution.
+
+**Wrong approach (paraphrased):**
+> "Many teams find navigation confusing in competitor products."
+
+**Right approach (verbatim quote):**
+> "158 users said 'confusing navigation between projects' has been open for 2 years. We redesigned for workflow, not feature hierarchy."
+
+The quote is the credibility anchor. Do not remove it.
+
+---
+
+## Ignored Demand: The Highest-Signal Category
+
+An issue that meets all three criteria:
+- 10+ reactions (significant real demand)
+- Open 180+ days (competitor has had time to act)
+- No planned/in-progress label (they have explicitly not prioritized it)
+
+This is not a feature request. This is a documented unmet need with a timestamp.
+
+**GTM translation:** "Their users asked. Their team did not respond. We built it."
+
+This framing works across all 6 categories. The combination of volume + age + inaction is the signal. The category determines the messaging angle.
+
+**Ignored demand outreach template:**
+```
+"[Competitor]'s users have been asking for [verbatim issue title] for [age].
+[Reaction count] teams upvoted it. There is no planned label.
+[Your product] handles this [natively / differently / as a core feature].
+[One-line ask]."
+```