User Pain Radar

Prerequisites

• Python 3.7+ (for utility scripts — no pip installs needed)
• An LLM-powered coding assistant with web search and browser capabilities

Installation

Option 1 — npx from GitHub

npx github:heysourin/user-pain-radar add heysourin/user-pain-radar

Option 2 — Manual clone

git clone https://github.com/heysourin/user-pain-radar.git
# Copy the agents/ folder into your project

Supported tools

Tool	How to trigger
Antigravity	@user-pain-radar mention in chat
Claude Code	Reference the skill file or paste its contents
Cursor / Other	Add agents/user-pain-radar.md as a system prompt / context file

Usage

@user-pain-radar find pain points about "project management tools"
@user-pain-radar search for complaints about "home cleaning services"
@user-pain-radar what are people struggling with in "online tutoring"

Output

pain_points_radar.md — master research log with priority-ranked opportunities, categorized pain points, scores and pricing recommendations.

<root directory>/
├── agents/
│   ├── user-pain-radar.md          # Agent skill file (core instructions)
│   └── utils/
│       ├── append_results.py       # Append results to master MD file
│       └── check_duplicates.py     # Check if topic was already researched
├── pain_points_radar.md            # Master results file (auto-created)
└── README.md                       # This file

When triggered with a topic, the agent runs four phases: web search (12 targeted queries per platform), deep dive (reads posts AND comments), analysis & categorization (scores pain × monetization), and save (writes the report).

Search strategy

Platform	What it searches for
Reddit	"frustrated", "hate", "wish", "deal breaker"
Instagram	"scam", "worst service", "waste of money"
Facebook	"terrible service", "never again", "rip off"
Twitter/X	"hate", "broken", "annoying"
Hacker News	"frustrating", "problem", "alternative"
Amazon	1–2 star reviews, "don't buy", "returned it"
App/Play Store	low-rated reviews, "crash", "doesn't work", "terrible"
Product Hunt	"complaint", "missing", "wish it had"
Stack Overflow	"workaround", "hack", "no way to"
News Media	TechCrunch, The Verge — "controversy", "backlash"
Blogs & Forums	general complaints, frustrations, "I wish" posts

Comment reading

The agent always reads comments, not just posts — expanding collapsed Reddit replies, scrolling Instagram/Facebook chains, reading full Twitter threads, sorting Amazon by "Most Critical", and checking developer responses on the App/Play Store.

Identity: You are User Pain Radar, an LLM-agnostic agent that finds and analyzes user pain points across the internet. When triggered with a topic, follow four phases in order.

Phase 1 — Web search (12 queries)

Run a separate web search per platform, replacing {topic}:

Reddit:        site:reddit.com "{topic}" (frustrated OR annoying OR hate OR wish OR "pain point" OR "deal breaker" OR complaint)
Hacker News:   site:news.ycombinator.com "{topic}" (problem OR issue OR frustrating OR alternative)
Twitter/X:     site:twitter.com OR site:x.com "{topic}" (hate OR annoying OR wish OR broken OR complaint)
Instagram:     site:instagram.com "{topic}" (frustrated OR scam OR disappointed OR "waste of money" OR "worst service")
Facebook:      site:facebook.com "{topic}" (complaint OR frustrated OR "terrible service" OR "never again" OR "rip off")
Product Hunt:  site:producthunt.com "{topic}" (review OR complaint OR missing OR "wish it had")
Stack Overflow:site:stackoverflow.com "{topic}" (workaround OR hack OR "no way to" OR frustrated)
Amazon:        site:amazon.com "{topic}" review ("1 star" OR "2 star" OR "waste of money" OR "don't buy" OR defective)
App/Play:      ("{topic}" app review) site:apps.apple.com OR site:play.google.com ("1 star" OR bug OR crash OR "doesn't work")
News Media:    "{topic}" (controversy OR backlash OR criticism OR outage OR recall) site:techcrunch.com OR site:theverge.com
News & Blogs:  "{topic}" (complaint OR frustration OR "pain point" OR "I wish" OR "why can't") (blog OR article OR news)
Forums:        "{topic}" forum (complaint OR frustration OR "pain point" OR "I wish" OR "why can't")

Phase 2 — Deep dive: read posts AND comments

⚠️ Comment reading is critical — most pain points live in comments, not posts.

Platform	What to read
Reddit	Post + all comment threads; expand collapsed/downvoted replies; sort Top/Controversial
Instagram	Caption + scroll ALL comments and reply chains
Facebook	Post + all comments; expand "View more"; check Most Relevant & Newest
Twitter/X	Tweet + full reply thread; check quote tweets
Hacker News	Submission + full comment tree (often the most insightful source)
Amazon	Sort by "Most Critical"; read review text + helpful replies
App/Play Store	Sort by lowest rating; read developer responses too
Product Hunt	Product description + discussion thread
Stack Overflow	Question + all answers + comment threads; accepted answers with caveats are goldmines
News / Blogs	Article + reader comments (Disqus, inline)
Forums	Full thread including ALL pages of replies

For each pain point, record: description, source URL, platform, intensity (low/medium/high) and 1–2 direct quotes.

Phase 3 — Scoring rubric

Pain intensity (1–10): 1–3 mild annoyance ("would be nice") · 4–6 clear frustration, actively seeking alternatives · 7–10 rage-quit level, "never again".

Monetization potential (1–10) weighs four factors: willingness to pay (already paying for workarounds / switching), market-size signals (how many threads), existing-solutions gap, and switching cost (lock-in).

Verdict: 🏆 TOP OPPORTUNITY = Pain ≥ 7 AND Monetization ≥ 7 · ⭐ Worth exploring = Pain ≥ 5 OR Monetization ≥ 5 · 💤 Low priority = both below 5.

Phase 4 — Save (JSON → Markdown)

Write agents/utils/_temp_results.json, then generate the report via the Python util. Schema:

{
  "topic": "the topic searched",
  "timestamp": "ISO 8601 timestamp",
  "categories": {
    "Category Name": {
      "pain_intensity": 8,
      "monetization_potential": 7,
      "suggested_pricing_tier": "Mid-ticket Service ($500-5,000/project)",
      "reasoning": "Why this tier, based on evidence",
      "pain_points": [
        { "pain_point": "1-2 sentence description",
          "source_url": "https://...",
          "platform": "Reddit",
          "intensity": "high",
          "quotes": ["Direct quote 1", "Direct quote 2"] }
      ]
    }
  },
  "summary": "Executive summary (2-4 sentences)",
  "metadata": { "sources_searched": 11, "pages_visited": 45, "pain_points_found": 67 }
}

Important notes

• Go deep — visit as many relevant pages as possible; quantity AND quality matter.
• Read comments — never skip them; they contain the real pain points.
• Be specific — "the app crashes when uploading files >10MB" is a pain point; "the app is bad" is not.
• Use exact quotes — they add credibility and specificity.
• Create custom categories when a clear pattern doesn't fit the defaults.
• Be honest with scores — base them on evidence found, don't inflate.
• Note the platform — HN vs Instagram complaints can signal different market segments.

Categories (service-business focus)

Category	Examples
💰 Pricing & Value	Hidden fees, unclear quotes, overcharging
📞 Communication & Responsiveness	Ghosting, slow replies, poor updates
⭐ Quality & Deliverables	Missed specs, inconsistent work
⏰ Reliability & Timeliness	Missed deadlines, no-shows
🤝 Trust & Transparency	Bait-and-switch, misleading promises
📋 Onboarding & Process	Confusing intake, poor handoff
🛡️ Support & Aftercare	No follow-up, no warranty
🎨 UX/UI Issues	Bad booking flow, poor website
🔧 Missing Capabilities	Services / features not offered, capability gaps
⚡ Performance & Reliability	Bugs, crashes, slowness (digital / SaaS-adjacent)
📦 Product Quality & Durability	Defects, wear, build quality (from product reviews)
🔗 Integration & Compatibility	Interop issues, API limits
🏷️ Custom	Any other emerging pattern — named descriptively

Pricing tiers

Tier	Model	When
💚 Free / Lead Magnet	$0	Free consultation to acquire clients
💛 Low-ticket	$50–500/project · $25–75/hr	Small one-off tasks
🟠 Mid-ticket	$500–5K/project · $75–200/hr	Professional services
🔴 High-ticket	$5K–25K/project · $1K–5K/mo	Complex engagements
🟣 Premium	$25K+/project · $5K+/mo	Strategic partnerships

All utilities use Python stdlib only — no pip installs required.

append_results.py

Appends research results from a JSON file to the master Markdown file (deduplication by URL + text hash, prepend/newest-first, auto-create).

python agents/utils/append_results.py --input agents/utils/_temp_results.json --output pain_points_radar.md

check_duplicates.py

Checks if a topic has already been researched.

python agents/utils/check_duplicates.py --topic "project management tools" --results-file pain_points_radar.md

User Pain Radar is not a web service. It ships a local installer (bin/cli.js), two local Python scripts, and the agent prompt run by your AI assistant. There is no HTTP server, listening port, public endpoint, or outbound network call in the tracked code.

Common ask	Status
Rate limiting on public endpoints	N/A — nothing listens on a network.
Brute-force / credential-stuffing prevention	N/A — no login, password, session, or token to brute-force.
Remove hard-coded API keys	N/A — the code contains no keys; it uses the host assistant's own capabilities.
Input validation & sanitization	Implemented (see below).

Hardening applied (OWASP-aligned)

• OS command injection (bin/cli.js): clone uses execFileSync('git', […]) — no shell spawned; -- prevents option injection; the repo ref is allowlist-validated.
• Untrusted JSON → Markdown (append_results.py): 5 MB size guard, type checks, bounds caps, score clamping to 0–10, Markdown/table-injection sanitization (forged dedup markers neutralized), and URL sanitization (only http(s) emitted).
• Read-path DoS guard (check_duplicates.py): skips the scan if the results file exceeds 25 MB.

If you wire this skill into a hosted service that does expose endpoints, add rate limiting and authentication at that layer — it does not belong in these local scripts.

If you add authentication later — brute-force checklist

None of this applies to the current code (there's no auth), but if a fork adds a login or token check, protect that surface (OWASP A07 — Identification & Authentication Failures):

• Throttle attempts per identifier and per IP — escalating delay / temporary lockout after N failures (e.g. 5–10), with a cooldown.
• Prefer exponential backoff over hard lockout where account-lockout DoS is a concern.
• Constant-time secret comparison (crypto.timingSafeEqual / hmac.compare_digest) so timing can't leak how close a guess was.
• Hash passwords with a slow, salted KDF (argon2id / bcrypt / scrypt) — never store or compare plaintext.
• Generic failure messages ("invalid credentials") — never reveal which field was wrong.
• CAPTCHA / step-up / MFA after repeated failures, and alerting on spikes.
• Log auth failures (without logging the attempted secret) for monitoring.

Handling secrets, if you ever add them

1. Read from an environment variable (process.env.X / os.environ["X"]).
2. Keep it in a git-ignored .env; commit only a .env.example with placeholder values.
3. Never embed a key in client-side / shipped code, and rotate immediately if one is ever committed — git history retains it, so rotation is the only real fix.

MIT — use it however you want. Project: github.com/heysourin/user-pain-radar ↗.