Map Your Market

Map Your Market

Take a product description, category keywords, or competitor names. Search Reddit, HN, GitHub Issues, G2, and Google Trends for real pain signals. Score and cluster them. Build a complete positioning framework: ICP definition, ranked pain themes with verbatim quotes, market size signals, and messaging angles derived from actual language people use.

---

Critical rule: Every pain quote in the output must exist verbatim in the raw data collected by the script. Every vendor name in the market map must come from G2 scrape results or GitHub search results. Market size must say "signals suggest" -- never estimate a dollar figure from thin proxies. If a source returns 0 results, report 0 -- do not supplement with invented examples.

---

Common Mistakes

| The agent will want to... | Why that's wrong | |---|---| | Invent pain points or market size numbers | Every pain quote must be verbatim from raw data. Market size must cite signals found. Never estimate "typical" market size. | | Score by post count instead of painscore | A post with 2,000 upvotes about pricing is stronger than 50 posts with 10 upvotes each. Use the painscore formula from references/pain-scoring.md. | | Use the same subreddits for every category | r/politics adds noise to a devops search. Auto-detect relevant subreddits from the category and competitor names before searching. | | Send all raw signals to AI without scoring | Score locally first. Send only the top 60 high-pain-score signals to AI clustering. Saves tokens and improves cluster quality. | | Skip ICP extraction from post metadata | Subreddit, flair, author bio (HN), and GitHub org type are richer ICP signals than post content. Always capture and report them. | | Conflate vendor count with market size | "47 vendors on G2" means competitive, not large. Present all signals as directional indicators, not hard numbers. |

---

Step 1: Setup Check

echo "GITHUB_TOKEN: ${GITHUB_TOKEN:-not set -- GitHub Issues search runs at 60 req/hr unauthenticated}"
echo "No other API keys required."
echo ""
echo "Data sources this run will use:"
echo "  Reddit public JSON  (no auth, 10 req/min)"
echo "  HN Algolia API      (no auth, free)"
echo "  GitHub Issues API   (${GITHUB_TOKEN:+authenticated, }60-5000 req/hr)"
echo "  G2 category scrape  (no auth, HTML parse)"
echo "  Google Trends       (no auth, unofficial endpoint)"

If GITHUB_TOKEN is not set: continue. Unauthenticated GitHub search is 60 req/hr -- enough for a standard run. For repeated use, add a token at github.com/settings/tokens (no scopes needed for public repos).

---

Step 2: Parse Input

Collect from the conversation:

• category -- keyword(s) describing the market space (e.g. "developer observability", "B2B analytics", "devops tooling")
• competitors -- optional list of competitor product names or domains (e.g. "Datadog, New Relic, Grafana")
• product_context -- optional: what the user's product does (helps tailor messaging angles)

If the user provides only a product description with no category keyword: extract 2-3 category keywords from it yourself.

If the user provides only competitor names with no category: infer the category by looking up competitors.

Write the parsed input:

python3 /dev/null && echo "script available" || echo "not found"

If available, run it:

GITHUB_TOKEN="${GITHUB_TOKEN:-}" python3 scripts/fetch.py \
    "$(python3 -c "import json; d=json.load(open('/tmp/mym-input.json')); print(d['category'])")" \
    --competitors "$(python3 -c "import json; d=json.load(open('/tmp/mym-input.json')); print(','.join(d['competitors']))")" \
    --context "$(python3 -c "import json; d=json.load(open('/tmp/mym-input.json')); print(d['product_context'])")" \
    --output /tmp/mym-raw.json

Wait for completion (allow up to 4 minutes -- Reddit + HN searches take ~90 seconds total).

Verify output:

python3 -c "
import json
with open('/tmp/mym-raw.json') as f:
    d = json.load(f)
print(f'Reddit signals: {d[\"market_signals\"][\"reddit_signals_found\"]}')
print(f'HN signals:     {d[\"market_signals\"][\"hn_signals_found\"]}')
print(f'GitHub signals: {d[\"market_signals\"][\"github_issue_signals\"]}')
print(f'G2 vendors:     {d[\"market_signals\"][\"vendor_count_g2\"]}')
print(f'Trends:         {d[\"market_signals\"][\"trends_direction\"]}')
print(f'Total signals:  {d[\"summary\"][\"total_pain_signals\"]}')
"

If total signals "{q}"') lines += ["", "---", "", "## Top Pains (ranked by signal strength)", ""]

for i, c in enumerate(clusters.get('clusters', []), 1): lines.append(f"### Pain {i}: {c['theme']} [score: {c['totalscore']}]") sources = c.get('sources', {}) sourcestr = " + ".join(f"{src} ({cnt})" for src, cnt in sources.items()) lines.append(f"{c['signalcount']} signals | Sources: {sourcestr}") lines.append(f"Who has this pain: {c.get('whohasthispain', '')}") lines.append("") lines.append("Verbatim:") for q in c.get('verbatimquotes', [])[:4]: lines.append(f'> "{q[\"text\"]}" ({q["source"]}, score: {q["score"]})') lines.append("")

lines += ["---", "", "## Market Map (Key Players)", ""] if marketmap: lines.append("| Vendor | Positioning |") lines.append("|---|---|") for v in marketmap: lines.append(f"| {v.get('name','')} | {v.get('positioning','')} |") else: top = ms.get('topvendors', []) if top: lines.append("| Vendor | G2 Reviews | Rating |") lines.append("|---|---|---|") for v in top: lines.append(f"| {v.get('name','')} | {v.get('reviewcount','')} | {v.get('rating','')} |")

lines += ["", "---", "", "## Messaging Framework", ""] for a in angles: lines.append(f"{a['pain']}: {a['statement']}") lines.append(f"Headline: \"{a['headline']}\"") lines.append(f"Cold email subject: \"{a['coldemailsubject']}\"") lines.append("")

lines += ["---", "", "## ICP Card", "", f"One liner: {icpcard.get('oneliner', '')}", "", f"Find them at: {', '.join(icpcard.get('wheretofindthem', []))}", "", f"How to talk to them: {icpcard.get('howtotalktothem', '')}", "", "---", "", "## Data Quality Notes", f"- All pain quotes are verbatim from raw signals", f"- All vendor names from G2 scrape", f"- Market size is directional only (no dollar estimates)", f"- Sources: Reddit ({ms['redditsignalsfound']}), HN ({ms['hnsignalsfound']}), GitHub Issues ({ms['githubissuesignals']}), G2 ({ms['vendorcountg2']} vendors)", "", f"Saved to: {outpathmd}", f"JSON snapshot: {outpath_json}", ]

with open(outpath_md, 'w') as f: f.write('\n'.join(lines))

Save JSON snapshot

snapshot = {"input": inp, "marketsignals": ms, "clusters": clusters.get('clusters', []), "icp": icp, "marketsize": marketassessment, "positioning": output, "date": date} with open(outpathjson, 'w') as f: json.dump(snapshot, f, indent=2)

print(f"Report saved: {outpathmd}") print(f"JSON snapshot: {outpathjson}") PYEOF

Clean up temp files:

```bash
rm -f /tmp/mym-input.json /tmp/mym-raw.json /tmp/mym-clusters.json /tmp/mym-output.json
echo "Done. Market map saved to docs/market-maps/"

Present the full contents of the saved .md file to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Varnan-Tech
• Source: Varnan-Tech/opendirectory
• License: MIT
• Homepage: https://www.opendirectory.dev

Install and usage instructions live in the source repository linked above.