# Recommendations

Read for recommendation intent before ranking and rendering. The root citation and output laws take precedence over presentation examples.

### If QUERY_TYPE = RECOMMENDATIONS — Signal-weighted picks, not mention counts

**The failure mode for RECOMMENDATIONS queries is "counting when you should have judged."** Mention count rewards whatever is already popular, which is rarely what is actually recommended. Rank by signal quality instead.

**Signal weights (highest to lowest):**
1. **Practitioner testimony** (weight 5) - first-person "I use X and here's why" with specific reasoning, version numbers, or workflow details
2. **Expert defection / authority move** (weight 4) - a domain insider publicly switching, endorsing, or picking (e.g., Flask creator switching from Python to Go)
3. **Measurable claim** (weight 4) - specific number, benchmark, production adoption proof (e.g., "43.7% latency win", "LinkedIn and Uber running it in prod")
4. **Reasoned comparison** (weight 3) - side-by-side analysis with tradeoffs explicitly named
5. **Pattern across independent sources** (weight 2) - multiple unaffiliated voices converging on the same pick
6. **Descriptive mention** (weight 1) - "X is a Python framework" — existence, not recommendation
7. **Promotional / bootcamp / course-caption** (weight 0) - "comment CODE for my course" — skip entirely, do not count

**Before ranking, separate "what EXISTS" from "what is RECOMMENDED":**
- EXISTS = descriptive mentions, promotional content, training-data inertia, bootcamp curriculum, "learn X first" posts with no stakes attached
- RECOMMENDED = reasoned picks from voices with stakes in the outcome (practitioners, experts, case studies, people who switched)
- Only RECOMMENDED items drive the top of the ranking. Existing-but-not-recommended items go in "Also mentioned" at the bottom with a one-line note on why they are mentions not picks.

**Lead with the 30-day DELTA, not the status-quo baseline.** What is the interesting movement? Who is switching? What is the contrarian signal? A status-quo leader with no movement is a footer item, not the headline. "Python has 15 mentions" is not a delta; "Flask creator switched to Go this month" is.

**Output shape:**

```
🏆 Top recommendations (ranked by signal quality, not mention count):

**[Pick 1]** - [one-line why it is the top recommendation based on the strongest signal in the research]
- Evidence: [specific practitioner testimony, benchmark number, or expert pick - quote the actual signal]
- Best for: [specific use case]
- Voices: [real @handles, publications, or r/subreddits with stakes in the outcome]

**[Pick 2]** - [same shape]

**[Pick 3]** - [same shape]

Also mentioned (exists, not recommended): [comma-separated list with one-line note on WHY each is a mention rather than a pick - e.g., "Python (status-quo default across bootcamp content; @javitm: 'agents have a strong bias for Python despite it probably not being the best')"]
```

**Anti-patterns to avoid:**
- Leading with the most-mentioned option because it appears most frequently ("Python has 15 mentions so it is #1"). That is counting, not judging.
- Treating every mention equally. A Flask-creator switching to Go (expert defection, weight 4) outranks 10 bootcamp captions saying "learn Python first" (promotional, weight 0). The bootcamp captions do not belong in the ranking at all.
- Collapsing "best for what?" into one leaderboard. RECOMMENDATIONS queries usually split into 2-4 sub-questions (best for production scale, best for agents to generate reliably, best for learning, best for benchmarks). Separate them if the research supports it.
- Ignoring anti-signal quotes. If the corpus contains a quote like "@javitm: agents have a strong bias for Python despite it probably not being the best — they prioritize the strongest signal in training data over the right choice," that is telling you mention-count is a biased metric for this topic. Read it; surface it; do not ignore it.
- Stress-test your top pick before emitting. Ask: "Would the research actually defend this claim to a skeptical expert?" If the answer is no, re-rank.

**BAD RECOMMENDATIONS synthesis (counting):**
> "🏆 Most mentioned: Python (15 mentions), TypeScript (10x), Go (7x), Rust (5x)."

**GOOD RECOMMENDATIONS synthesis (judging):**
> "🏆 Top recommendations (ranked by signal quality, not mention count):
>
> **Go** - Flask creator Miguel Grinberg publicly switched this month for a specific technical reason
> - Evidence: @miguelgrinberg blog post "Why I am moving Python projects to Go for AI agents" — cites reliability and concurrency model; 1.2K upvotes on r/programming
> - Best for: production agent infrastructure
> - Voices: @miguelgrinberg, r/programming, r/golang
>
> **Rust** - Hardest numbers in the corpus
> - Evidence: production benchmark showing 43.7% latency reduction and 16x throughput growth in agent workloads; LangChain Rust port announcement
> - Best for: performance-critical agent runtimes
> - Voices: @langchainai, r/rust, Hacker News
>
> **TypeScript** - Strongest production-adoption signal
> - Evidence: LinkedIn, Uber, and Klarna running LangGraph.js in prod per LangChain blog
> - Best for: agents that integrate with existing web stacks
> - Voices: @hwchase17, @LangChainAI, r/LocalLLaMA
>
> Also mentioned (exists, not recommended): Python (status-quo default across training data and bootcamp content; @javitm: 'agents have a crazy strong bias for Python despite it probably not being the best — they prioritize the strongest signal in training data over the right choice'), Java/Kotlin (enterprise mentions only, no practitioner testimony in the 30-day window)."

Notice how the good version:
- Leads with movement (Flask creator switched), not volume (Python has most mentions)
- Cites specific evidence that would defend the ranking to a skeptic
- Treats Python's volume as anti-signal (the @javitm quote) rather than support
- Puts promotional / descriptive mentions in "Also mentioned" with explicit framing


**Rendering:** use the signal-quality template above; mention counts do not determine ranking.

**CRITICAL for RECOMMENDATIONS:**
- Each item MUST have a "Voices:" line with actual @handles from X posts (e.g., @LONGLIVE47, @ByDobson)
- Include subreddit names (r/hiphopheads) and web sources (Complex, Variety)
- Parse @handles from research output and include the highest-engagement ones
- Format naturally - tables work well for wide terminals, stacked cards for narrow
- **CRITICAL whitespace rule:** Never insert more than ONE blank line between any two content blocks. Comparison tables should immediately follow the preceding paragraph with exactly one blank line. Do NOT pad with 3-6 empty lines before tables.