# Discovery Agent

Execute the Discovery phase of Symph Agency pipeline. Market scanning, opportunity identification, and PRD generation for Symph Agency Discovery phase. Use when starting a new product, validating market opportunities, or generating PRDs.

## Capabilities

1. **Trend Scanner** — Scan HN, Exploding Topics for emerging opportunities
2. **Opportunity Scorer** — Rate opportunities with transparent criteria
3. **Pain Point Miner** — Extract real user complaints from Reddit via search
4. **PRD Generator** — Generate full discovery artifacts when opportunity approved

---

## Opportunity Scoring System

### Score Range: 1.0 - 5.0

| Score | Rating | Meaning |
|-------|--------|---------|
| 4.5+ | Exceptional | Strong market, clear pain, low competition |
| 4.0-4.4 | Strong | Good fundamentals, worth pursuing |
| 3.5-3.9 | Promising | Potential with some risks |
| 3.0-3.4 | Moderate | Needs validation |
| <3.0 | Weak | High risk, skip unless strategic |

### Scoring Criteria (each 1-5, weighted)

| Factor | Weight | What We Measure |
|--------|--------|-----------------|
| **Market Size** | 25% | TAM >$1B = 5, >$500M = 4, >$100M = 3 |
| **Growth Trend** | 25% | >5000% = 5, >2000% = 4, >500% = 3 |
| **Problem Clarity** | 20% | Clear pain point with evidence |
| **Competition Gap** | 15% | No dominant player = 5, fragmented = 4 |
| **Symph Fit** | 15% | Aligns with our skills (SaaS, B2B, local) |

### Score Explanation Format

When presenting opportunities, always include:

```markdown
## Why This Scores [X.X]

**Market Size (X/5):** $X.XB market, growing at X% CAGR
**Growth Trend (X/5):** X,XXX% search growth (Exploding Topics)
**Problem Clarity (X/5):** [Clear pain point evidence]
**Competition Gap (X/5):** [Current landscape analysis]
**Symph Fit (X/5):** [Why we can win here]

**Bottom Line:** [1-2 sentence summary of why this is promising]
```

---

## When Opportunity is Approved → Generate Discovery Artifacts

When a user approves an opportunity, create these files in `agency/products/[slug]/discovery/`:

### 1. product-brief.md
```markdown
# Product Brief: [Name]

## The Opportunity
[Why this market, why now]

## Problem Statement
[Specific pain point we're solving]

## Proposed Solution
[High-level product concept]

## Why Us
[Why Symph can win here]

## Success Criteria
[How we'll know this worked]
```

### 2. target-market.md
```markdown
# Target Market Analysis

## Market Sizing
- **TAM:** Total Addressable Market
- **SAM:** Serviceable Addressable Market
- **SOM:** Serviceable Obtainable Market (Year 1)

## Primary Persona
[Who is the ideal customer]

## Geographic Focus
[Where we'll start]

## Willingness to Pay
[Price sensitivity, comparable spend]
```

### 3. competitors.md
```markdown
# Competitor Analysis

## Direct Competitors
| Name | Strengths | Weaknesses | Pricing |
|------|-----------|------------|---------|

## Indirect Competitors
[Adjacent solutions customers use today]

## Our Differentiation
[How we'll be different/better]
```

### 4. prd.md
```markdown
# Product Requirements Document

## Overview
[Product vision in 2-3 sentences]

## Goals
- Primary goal
- Secondary goals

## Non-Goals
[What we're NOT building]

## User Stories

### P0 (Must Have)
- As a [user], I want [feature], so that [benefit]

### P1 (Should Have)
- ...

### P2 (Nice to Have)
- ...

## Success Metrics
| Metric | Target | Timeframe |
|--------|--------|-----------|

## Open Questions
[Things to validate]
```

### 5. user-stories.md
```markdown
# User Stories

## Epic 1: [Core Workflow]

### P0 - Must Have
- [ ] US-001: As a [user], I want [action], so that [benefit]
- [ ] US-002: ...

### P1 - Should Have
- [ ] US-010: ...

### P2 - Nice to Have
- [ ] US-020: ...

## Acceptance Criteria
[How we'll know stories are done]
```

### 6. opportunity-score.md
```markdown
# Opportunity Score Breakdown

**Overall Score: X.X / 5.0**

## Scoring Details

| Factor | Score | Weight | Weighted |
|--------|-------|--------|----------|
| Market Size | X.X | 25% | X.XX |
| Growth Trend | X.X | 25% | X.XX |
| Problem Clarity | X.X | 20% | X.XX |
| Competition Gap | X.X | 15% | X.XX |
| Symph Fit | X.X | 15% | X.XX |
| **Total** | | | **X.XX** |

## Rationale

### Market Size (X.X/5)
[Evidence and reasoning]

### Growth Trend (X.X/5)
[Source data and analysis]

### Problem Clarity (X.X/5)
[Pain point evidence]

### Competition Gap (X.X/5)
[Competitive landscape]

### Symph Fit (X.X/5)
[Why we can execute]

## Recommendation
[GO / REVISE / PASS with reasoning]
```

### 7. user_complaints.md
```markdown
# User Complaints Analysis

Source: Reddit via Brave Search
**⚠️ GUARDRAIL: All quotes MUST be from verified real users (not marketing/news)**

## Validation Summary
| Metric | Count |
|--------|-------|
| Results scanned | X |
| Valid (included) | X |
| Excluded (non-user) | X |

## Performance Issues (X mentions)
- [HIGH] "[Quote from Reddit]" — r/[subreddit], [date]
  └─ Verified: First-person experience
- [MEDIUM] "[Quote]" — r/[subreddit], [date]

## Pricing Concerns (X mentions)
- [HIGH] "[Quote]" — r/[subreddit], [date]

## UX/Complexity Issues (X mentions)
- [HIGH] "[Quote]" — r/[subreddit], [date]

## Missing Features (X mentions)
- [HIGH] "[Quote]" — r/[subreddit], [date]

## Data/Privacy Concerns (X mentions)
- [HIGH] "[Quote]" — r/[subreddit], [date]

## Key Insight
[Most frequent/severe complaint pattern]
```

**Source Validation Rules:**
- ✅ Include: Reddit posts, forum comments, user reviews (first-person)
- ❌ Exclude: Company blogs, news articles, listicles, promotional content
- Tag confidence: [HIGH] = specific + recent, [MEDIUM] = vague or older

### 8. switching_reasons.md
```markdown
# Why Users Switch From Competitors

## Top Switching Reasons (ranked by frequency)

### 1. [Reason] (X mentions)
- "[Quote]" — r/[subreddit]
- "[Quote]" — r/[subreddit]

### 2. [Reason] (X mentions)
- "[Quote]" — r/[subreddit]

### 3. [Reason] (X mentions)
- "[Quote]" — r/[subreddit]

## Implication for Our Product
[How we should position against these pain points]
```

### 9. competitor_mentions.md
```markdown
# Competitors Mentioned in User Discussions

| Competitor | Mentions | Context | Sentiment |
|------------|----------|---------|-----------|
| [Name] | X | "Switched to [Name] because..." | Positive |
| [Name] | X | "Tried [Name] but..." | Mixed |

## Competitor Positioning Map
- **[Competitor A]**: Known for [strength], criticized for [weakness]
- **[Competitor B]**: Known for [strength], criticized for [weakness]

## Gap We Can Exploit
[Underserved need based on complaints]
```

---

## Pain Point Miner — How It Works

### When to Run
After opportunity scoring, BEFORE generating PRD. This enriches the PRD with validated pain points.

### ⚠️ Rate Limit Handling

**Brave API Limits (Free Tier):**
- Rate: 1 request/second
- Quota: 2,000 searches/month

**Mitigation Strategy:**

1. **Check quota before running:**
```
If rate_limit_error (429) → wait 2 sec, retry once
If quota_exhausted → SKIP pain point mining, continue with PRD
```

2. **Graceful degradation:**
```markdown
# In PRD when skipped:
## Pain Points
⚠️ Pain point analysis skipped (API quota exhausted)
Recommend manual review of Reddit/G2 for competitor complaints.
```

3. **Log skips for tracking:**
```yaml
# agency/data/pain-point-miner-metrics.yaml
- product: "example"
  date: 2026-02-13
  status: "skipped"
  reason: "quota_exhausted"
```

### Search Queries (Optimized — Batched)

**Use category-level searches instead of per-competitor (reduces API calls):**

```
# 3 searches instead of 9
web_search("[product category] problems OR complaints OR frustrating site:reddit.com", count=10)
sleep(2)
web_search("[product category] switched from OR moved to OR ditched site:reddit.com", count=10)
sleep(2)
web_search("[competitor1] vs [competitor2] vs [competitor3] reddit", count=10)
```

**Fallback (if batched search too broad):**
```
web_search("[top competitor] problems OR issues site:reddit.com", count=10)
sleep(2)
web_search("[top competitor] switched from site:reddit.com", count=10)
```

### Pain Point Categories
| Category | Keywords to Look For |
|----------|---------------------|
| **Performance** | slow, laggy, takes forever, loading, crash |
| **Pricing** | expensive, not worth, overpriced, free alternative |
| **UX/Complexity** | confusing, complicated, learning curve, overwhelming |
| **Mobile/Offline** | mobile app sucks, offline, sync issues |
| **Missing Features** | wish it had, doesn't support, can't do, need |
| **Data/Privacy** | own my data, privacy, export, lock-in, vendor |
| **Support** | support sucks, no response, unhelpful |

### Output
Creates 3 new files in discovery artifacts:
- `user_complaints.md` — Categorized complaints with quotes
- `switching_reasons.md` — Why users leave competitors  
- `competitor_mentions.md` — Who else is in the space

---

## 📊 Metrics Logging (REQUIRED)

**After EVERY pain-point-miner run, update:**
`agency/data/pain-point-miner-metrics.yaml`

### What to Log

```yaml
# 1. Update quota_status
quota_status:
  searches_used: [increment by searches made]
  searches_remaining: [decrement by searches made]
  last_updated: [current timestamp]

# 2. Update rate_limit_stats (if any 429s hit)
rate_limit_stats:
  hits_this_month: [increment if hit]
  last_hit: [timestamp if hit]
  retries_succeeded: [increment if retry worked]
  retries_failed: [increment if retry failed]

# 3. Update skip_stats (if skipped)
skip_stats:
  skips_this_month: [increment if skipped]
  skip_reasons:
    quota_exhausted: [increment if reason]
    rate_limited: [increment if reason]

# 4. Add run entry
runs:
  - product: "[slug]"
    date: "[YYYY-MM-DD]"
    timestamp: "[ISO timestamp]"
    status: "[success|partial|skipped]"
    searches_attempted: [N]
    searches_completed: [N]
    rate_limit_hits: [N]
    retries: [N]
    total_time_sec: [N]
    pain_points_extracted: [N]
    categories_found: [list]
    skip_reason: [null|quota_exhausted|rate_limited]
    quota_after_run: [remaining quota]
    human_feedback: null  # Fill after human review
```

### Check Before Running

```python
# Pseudo-code: Check quota before starting
quota_remaining = read_yaml("agency/data/pain-point-miner-metrics.yaml")["quota_status"]["searches_remaining"]
searches_needed = 3  # batched queries

if quota_remaining < searches_needed:
    log_skip(reason="quota_exhausted")
    return "SKIPPED"
else:
    run_searches()
    update_metrics()
```

### Alert Thresholds

| Metric | Threshold | Action |
|--------|-----------|--------|
| `searches_remaining` < 200 | Low quota warning | Consider upgrade |
| `rate_limit_hits` > 10/day | Frequent limits | Increase delays |
| `skips_this_month` > 5 | Too many skips | Upgrade tier |

---

## Data Sources

### ✅ Working Sources (web_fetch)

| Source | URL | Best For |
|--------|-----|----------|
| **Hacker News Show** | `news.ycombinator.com/show` | Tech products, dev tools |
| **Exploding Topics** | `explodingtopics.com/blog/trending-topics` | Consumer trends with growth |
| **BetaList** | `betalist.com` | Early-stage startups |

### ✅ Working Sources (web_search — Brave API)

| Source | Query Pattern | Best For |
|--------|---------------|----------|
| **Reddit complaints** | `[category] problems site:reddit.com` | User pain points |
| **Switching signals** | `[product] switched from site:reddit.com` | Why users leave |
| **Alternatives** | `[product] vs [competitor] reddit` | Competitor landscape |

**See also:** `skills/pain-point-miner/SKILL.md` for detailed extraction workflow

### 📊 Metrics File
`agency/data/pain-point-miner-metrics.yaml` — Track quota, rate limits, effectiveness

---

## Workflow

### Path 1: Autonomous Discovery Scan

```
1. Fetch HN Show + Exploding Topics
2. Extract signals and categorize
3. Score each opportunity (5 criteria)
4. Save to agency/discovery/opportunities.yaml with explanations
5. Present top 5 to human
```

### Path 2: Opportunity Approval

```
1. Human selects opportunity from scan
2. Create product folder: agency/products/[slug]/
3. Identify top 2-3 competitors in the space
4. 🆕 RUN PAIN POINT MINER (with graceful degradation):
   │
   ├─► TRY: Batched category searches (3 searches total)
   │   - "[category] problems OR complaints site:reddit.com"
   │   - "[category] switched from site:reddit.com"
   │   - "[competitor1] vs [competitor2] reddit"
   │   - (2 sec delay between each)
   │
   ├─► IF rate_limit (429): Wait 2 sec, retry once
   │
   ├─► IF quota_exhausted: 
   │   - Log skip to metrics file
   │   - Continue WITHOUT pain point files
   │   - Add "⚠️ skipped" note to PRD
   │
   └─► IF success:
       - Categorize complaints by theme
       - Generate: user_complaints.md, switching_reasons.md, competitor_mentions.md
       
5. Generate remaining discovery artifacts (enriched if pain points available)
6. Update progress.md with status
7. Set workflow.json to "review"
8. Notify human for approval
```

### Path 3: Human Gate

Present discovery for approval:
- ✅ Approve → Advance to Design phase
- 🔄 Revise → Address feedback
- ❌ Reject → Archive with learnings

---

## Opportunity YAML Format

```yaml
opportunities:
  - id: opp-1
    name: "Product Name"
    sector: "Industry / Category"
    marketSize: "$X.XB"
    score: 4.2
    description: "One-liner pitch"
    source: "Exploding Topics"
    growth_trend: "2,800%"
    score_breakdown:
      market_size: 4.0
      growth_trend: 4.5
      problem_clarity: 4.0
      competition_gap: 4.0
      symph_fit: 4.5
    why_promising: |
      Clear pain point in growing market. No dominant player.
      Aligns with Symph's B2B SaaS expertise.
```

---

## Quick Reference

### Run Discovery Scan
```
1. web_fetch: news.ycombinator.com/show
2. web_fetch: explodingtopics.com/blog/trending-topics
3. Score opportunities (5 criteria each)
4. Save to agency/discovery/opportunities.yaml
5. Notify human with top 5
```

### Approve Opportunity
```
1. Create agency/products/[slug]/discovery/
2. Identify top 2-3 competitors
3. Run Pain Point Miner:
   - web_search("[competitor] problems site:reddit.com")
   - web_search("[competitor] switched from site:reddit.com")
   - web_search("[competitor] alternatives site:reddit.com")
   - (1-2 sec delay between searches to avoid rate limit)
4. Generate: user_complaints.md, switching_reasons.md, competitor_mentions.md
5. Generate: product-brief.md, target-market.md, competitors.md, prd.md, user-stories.md, opportunity-score.md
   (PRD now enriched with validated pain points)
6. Set workflow.json status: "review"
7. Update progress.md
8. Notify human
```
