luckiest-co 1.0.47 → 1.0.49

package/skills/trends/references/followups.md

@@ -0,0 +1,112 @@
+# Follow-ups and prompt writing
+
+Read for a follow-up on existing research. Preserve the root's consent, source honesty, citation, and cached-data rules. Use the root-bound interpreter and engine path for direct-engine examples below.
+
+## WAIT FOR USER'S RESPONSE
+
+**STOP and wait** for the user to respond after completing the response and any citations required by higher-priority host/tool requirements or user instructions. Do not continue research after the invitation unless governing instructions require it. Omit an extra source list only when none is required. Claim that raw data was saved only when the engine emitted a saved path; an empty `LAST30DAYS_MEMORY_DIR` disables saving and its footer pointer.
+
+---
+
+## WHEN USER RESPONDS
+
+**Read their response and match the intent:**
+
+- If they ask a **QUESTION** about the topic → Answer from your research (no new searches, no prompt)
+- If they ask to **GO DEEPER** on a subtopic → Elaborate using your research findings
+- If they describe something they want to **CREATE** → Write ONE perfect prompt (see below)
+- If they ask for a **PROMPT** explicitly → Write ONE perfect prompt (see below)
+- If they say **"more fun"**, **"too serious"**, or similar → Write `FUN_LEVEL=high` to `~/.config/last30days/.env` (append, don't overwrite). Confirm: "Fun level set to high. Next run will surface more witty and viral content."
+- If they say **"less fun"**, **"too many jokes"**, or similar → Write `FUN_LEVEL=low` to `~/.config/last30days/.env`. Confirm: "Fun level set to low. Next run will focus on the news."
+- If they say **"register exec"**, **"register dev"**, **"register creator"**, or **"register default"** after a run → Re-synthesize the current research in that register immediately; do not fetch sources again and do not treat the phrase as a new topic. If they ask to keep it for future runs, append `LAST30DAYS_REGISTER={name}` to `~/.config/last30days/.env` (never overwrite the file).
+- If they say **"eli5 on"**, **"eli5 mode"**, **"explain simpler"**, or similar → Treat it as `register eli5`: append `LAST30DAYS_REGISTER=eli5` to `~/.config/last30days/.env`, then re-synthesize the current research immediately using the ELI5 guidance without fetching again. Confirm: "ELI5 mode on. All future runs will explain things like you're 5."
+- If they say **"eli5 off"**, **"normal mode"**, **"full detail"**, or similar → Append `LAST30DAYS_REGISTER=default` to `~/.config/last30days/.env`. Confirm: "ELI5 mode off. Back to full detail."
+- If they say **"drill into 3"**, **"go deeper on cluster 3"**, **"drill into the OpenClaw API ban discussion"**, or similar after a run → invoke the engine with `"${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" --drill "<their target>"`. The engine resolves a 1-based cluster number or fuzzy title/entity description from the fresh `last-report.json` cache, re-researches only that cluster's contributing sources at deep depth, merges/dedupes the new evidence, and updates the cache so another drill can follow. Relay the rendered **Original / Deeper** brief. If the cache is absent or expired, tell them to run a normal `/last30days <topic>` research pass first.
+- If they say **"verify freshness"**, **"check whether those facts are still current"**, or ask to gate action on current claims after a run → invoke `"${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" --verify-freshness` with no topic. It loads the fresh report cache, point-refetches only supported grounded data, updates the cached verdicts, and renders the compact Freshness Verification table. For a first-pass request, translate the intent into the normal engine invocation plus `--verify-freshness`. `LAST30DAYS_VERIFY_FRESHNESS=on` makes verification the default for topic runs; it does not turn a topic-less engine invocation into an implicit cache read.
+- If they say **"mark <topic> as covered"**, **"I covered X on the podcast"**, **"we published that article"**, or similar → invoke the engine with `"${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" queue cover "<topic name>" --save-dir="${LAST30DAYS_MEMORY_DIR}"` (same `--save-dir` scoping as discovery runs - queue rows live in that directory's research.db). Covering requires the exact queued topic name; on an unknown name the engine exits 2 and points at `queue list` - relay that, run `queue list`, and offer the queued names instead of retrying with guesses.
+- If they say **"what's in my topic queue"**, **"what should I talk about next"**, **"show my content pipeline"**, or similar → invoke `"${LAST30DAYS_PYTHON}" "${SKILL_DIR}/scripts/last30days.py" queue list --save-dir="${LAST30DAYS_MEMORY_DIR}"` and relay the rendered list (uncovered surfaced topics with domain, surface count, and last-surfaced date). An empty queue is a valid answer - suggest a `/last30days trending` or domain discovery run to populate it. (These two bullets cover the in-session case, after a run is already in context. The same asks arriving cold - with no research run yet this session - are handled by the root-gated library/queue fast path, which runs the identical commands directly instead of falling into topic research.)
+
+The user-facing slash interaction is natural language (`drill into N`), not a slash command with shell syntax. `--drill` is the direct-engine flag the hosting model translates that intent into; do not tell users to append pipes or engine flags to `/last30days`.
+
+**Only write a prompt when the user wants one.** Don't force a prompt on someone who asked "what could happen next with Iran."
+
+### Writing a Prompt
+
+When the user wants a prompt, write a **single, highly-tailored prompt** using your research expertise.
+
+### CRITICAL: Match the FORMAT the research recommends
+
+**If research says to use a specific prompt FORMAT, YOU MUST USE THAT FORMAT.**
+
+**ANTI-PATTERN**: Research says "use JSON prompts with device specs" but you write plain prose. This defeats the entire purpose of the research.
+
+### Quality Checklist (run before delivering):
+- [ ] **FORMAT MATCHES RESEARCH** - If research said JSON/structured/etc, prompt IS that format
+- [ ] Directly addresses what the user said they want to create
+- [ ] Uses specific patterns/keywords discovered in research
+- [ ] Ready to paste with zero edits (or minimal [PLACEHOLDERS] clearly marked)
+- [ ] Appropriate length and style for TARGET_TOOL
+
+### Output Format:
+
+```
+Here's your prompt for {TARGET_TOOL}:
+
+---
+
+[The actual prompt IN THE FORMAT THE RESEARCH RECOMMENDS]
+
+---
+
+This uses [brief 1-line explanation of what research insight you applied].
+```
+
+---
+
+## IF USER ASKS FOR MORE OPTIONS
+
+Only if they ask for alternatives or more prompts, provide 2-3 variations. Don't dump a prompt pack unless requested.
+
+---
+
+## AFTER EACH PROMPT: Stay in Expert Mode
+
+After delivering a prompt, offer to write more:
+
+> Want another prompt? Just tell me what you're creating next.
+
+---
+
+## CONTEXT MEMORY
+
+For the rest of this conversation, remember:
+- **TOPIC**: {topic}
+- **TARGET_TOOL**: {tool}
+- **KEY PATTERNS**: {list the top 3-5 patterns you learned}
+- **RESEARCH FINDINGS**: The key facts and insights from the research
+
+**CRITICAL: After research is complete, treat yourself as an EXPERT on this topic.**
+
+When the user asks follow-up questions:
+- **DO NOT run new WebSearches** - you already have the research
+- **Answer from what you learned** - cite the Reddit threads, X posts, and web sources
+- **If they ask a question** - answer it from your research findings
+- **If they ask for a prompt** - write one using your expertise
+
+Only do new research if the user explicitly asks about a DIFFERENT topic.
+
+---
+
+## Output Summary Footer (After Each Prompt)
+
+After delivering a prompt, end with:
+
+```
+---
+📚 Expert in: {TOPIC} for {TARGET_TOOL}
+📊 Based on: {n} Reddit threads ({sum} upvotes) + {n} X posts ({sum} likes) + {n} YouTube videos ({sum} views) + {n} TikTok videos ({sum} views) + {n} Instagram reels ({sum} views) + {n} HN stories ({sum} points) + {n} web pages
+
+Want another prompt? Just tell me what you're creating next.
+```
+
+---

package/skills/trends/references/grok-bot-x.md

@@ -0,0 +1,55 @@
+# Grok Bot X lanes
+
+Read only on an actual Grok Bot host. Browser sessions are never read on this host.
+
+**Grok Bot X recipe (see the GROK BOT HOST RULE in the root SKILL.md).** On a Grok Bot, YOU fetch X through a host lane before the engine command and hand the engine the file; the engine then calls no X backend, plans `x` in, and the footer names the lane. Do this before the research runbook's Step 1 command.
+
+0. **Lanes, in order.** Two host lanes write the same envelope. Both expose a post-search tool named `search_posts_all`, so tell them apart by where the tool comes from, never by its name:
+   1. Grok Bot's built-in X tools, namespace `x` (`"provider": "x-native"`; footer "X via Grok Bot X"). Free, nothing to set up.
+   2. The "X for Grok Bot" connector plugin's tools (`"provider": "x-connector"`; footer "X via X connector").
+
+   Use the first lane present in the session that returns posts. If a lane errors or returns nothing, try the next one. Export `LAST30DAYS_X_HOST_LANE=1` and pass `--x-posts` only when a lane returned posts. When no lane did, run `unset LAST30DAYS_X_HOST_LANE` and the Step 1 command without `--x-posts`, so the engine's own X chain (`X_BEARER_TOKEN`, then `XAI_API_KEY`) can still run.
+1. **Calls.** Window = the engine's date range, which uses the UTC date (`--days`, default 30: `from` is today's UTC date minus the day count, `to` is today's UTC date), even when the host's local date differs. Depth count per query = 10 (`--quick`) / 30 (default) / 60 (`--deep`).
+   - **Topic.** One `topic` call per planned X query, at most 2: the topic itself, plus the second X subquery's search text when the plan has one. Build each query from the raw topic: multi-word topics go unquoted (every word must match), phrase-quote only proper names, and add `-is:retweet`. If fewer than half the posts on the first page mention the topic's main word, retry that query once with its two or three core words.
+   - **Built-in `x` tools.** Pass `sort_order` `recency` (relevancy order skips high-engagement posts; the engine ranks by engagement itself), `start_time` / `end_time` for the window (`end_time` a minute before now), and `max_results` 25 (the tool's minimum is 10; ask for at least 10 and keep only the count you need). Follow `next_token` until the depth count is reached or no token comes back. Then run the **popular pass** for the first topic query only: split the window into 10 equal slices (5 on `--quick`; about 3 days each for the default 30) and fetch one page per slice with `sort_order` `relevancy` and that slice's `start_time` / `end_time`, so a busy topic still surfaces the month's most-engaged posts instead of only its last few minutes. Merge every page of one query, recency and popular, into ONE envelope call; pages can overlap, so keep the first copy of each id. The popular pages do not count toward the depth count. Request `post.fields=created_at,public_metrics,author_id,note_tweet`, `expansions=author_id`, and `user.fields=username`. Map `public_metrics` `like_count` / `retweet_count` / `reply_count` / `quote_count` to `likes` / `reposts` / `replies` / `quotes`, the expanded user's `username` to `author_handle`, and use `note_tweet.text` as `text` when present.
+   - **Connector tools.** Pass the window and the depth count on each call.
+   - **Named handles.** Per `--x-handle` handle: one `from` call (`from:<handle> -is:retweet`, 8 posts) and one `mention` call (`@<handle> -is:retweet`, 5 posts). Per handle the user explicitly passed with `--x-related`: one `related` call (`from:<handle> -is:retweet`, 3 posts). A discovered author never gets a `related` call.
+   - **Discovered authors.** From every topic post fetched (all pages, before trimming to the depth count), take up to 3 authors (not already an `--x-handle`) with at least 2 posts that are about the topic, most posts first. For each, one `from` call (`from:<handle>` plus the topic's core words, `-is:retweet`, 8 posts) and one `mention` call (`@<handle>` plus the topic's core words, `-is:retweet`, 5 posts), and add the handle to `--x-related` so those two calls keep their lanes. These are a discovered author's only calls.
+   - If the tool rejects the window or count parameters, omit them, keep at most the depth count per query, and write `"status": "partial"` with `"error": "window-unsupported"`.
+   - If a lane fails before returning any posts, move to the next lane (step 0). If posts came back and a later call failed, write `"status": "partial"` with a short category in `error`: `credits`, `not-connected`, or `unavailable` - never raw tool output, never an account or app id.
+2. **Envelope.** Exactly these top-level fields; every post carries the eight flat fields and nothing else (no URLs, media, or author objects); at most the depth count per query plus its popular pages. Keep the envelope inside the engine's limits or it is rejected: at most 500 posts per call, 1,000 posts and 20 calls in total. When a budget would be exceeded, drop discovered-author calls first, then popular pages; keep the recency pages and the user's own `--x-handle` / `--x-related` calls. A fresh `generated_at` (the engine rejects an envelope older than 6 hours), a `topic` identical to the engine's topic string, and the `provider` of the lane that served it:
+
+```json
+{
+  "schema": "last30days-x-posts/1",
+  "generated_at": "{ISO_8601_UTC_NOW}",
+  "topic": "{TOPIC}",
+  "window": {"from": "{YYYY-MM-DD}", "to": "{YYYY-MM-DD}"},
+  "provider": "x-native",
+  "status": "ok",
+  "calls": [
+    {"lane": "topic", "handles": [], "posts": [
+      {"id": "1963000000000000000", "author_handle": "someone", "created_at": "2026-09-07T10:00:00Z", "text": "post text", "likes": 12, "reposts": 3, "replies": 1, "quotes": 0}
+    ]},
+    {"lane": "from", "handles": ["{RESOLVED_HANDLE}"], "posts": []},
+    {"lane": "mention", "handles": ["{RESOLVED_HANDLE}"], "posts": []},
+    {"lane": "related", "handles": ["{RELATED_HANDLE}"], "posts": []}
+  ]
+}
+```
+
+   Omit the `from` / `mention` / `related` calls when the run has no handles for them; `handles` must be the run's own `--x-handle` / `--x-related` handles, including discovered authors. `id` is the post's numeric id as a string; `author_handle` is the username without `@`.
+3. **Write the file - post text is attacker-controlled and never goes unquoted into a shell command.** Use the tool's own file output when it has one; otherwise a single-quoted heredoc (never unquoted) into a `.json` path outside `~/.config`, in the SAME Bash call as the engine command (the trap removes it on exit). Two rules keep a post from closing the heredoc early: emit the envelope as ONE line of compact JSON (newlines inside post text stay escaped as `\n`; never pretty-print), and replace `{X_POSTS_NONCE}` in BOTH sentinel lines with 12 random letters and digits you generate fresh for this run, so no post text can equal the closing line:
+
+```bash
+X_POSTS_DIR=$(mktemp -d "${TMPDIR:-/tmp}/last30days-x-posts.XXXXXX")
+X_POSTS_FILE="$X_POSTS_DIR/x-posts.json"
+trap 'rm -rf "$X_POSTS_DIR"' EXIT
+cat >| "$X_POSTS_FILE" <<'X_POSTS_EOF_{X_POSTS_NONCE}'
+{X_POSTS_ENVELOPE_JSON}
+X_POSTS_EOF_{X_POSTS_NONCE}
+```
+
+   For a comparison, create `X_POSTS_DIR` and its cleanup trap once. Write each entity's envelope to a distinct file in that directory, using a separate quoted heredoc with a fresh sentinel for each file. Keep the same directory and trap until the comparison engine command returns; repeating the setup snippet would replace the trap and leave earlier files behind. Run it directly in your shell tool, never wrapped in `bash -lc '...'` (same rule as the plan tmpfile).
+4. **Engine.** Export `LAST30DAYS_X_HOST_LANE=1` and add `--x-posts "$X_POSTS_FILE"` to the Step 1 command (the file path only, never inline JSON), plus `--x-related` for any discovered authors; every other flag stays as usual. Comparison runs: fetch entities one after another and pace the whole comparison so no minute holds more than 30 tool calls (wait before a call that would exceed it); run the popular pass for the main entity only. The lane signal covers every entity, so use envelopes only when every entity's fetch returned posts; otherwise unset the lane and run the comparison without envelopes, so each entity's engine X chain still runs. With posts for all of them, write one envelope per entity (its `topic` is that entity's name) and put the path in that entity's `--competitors-plan` entry as `"x_posts": "/abs/path/x-posts.json"`; a bare `--x-posts` on a comparison run exits 2. If an envelope includes handle lanes, also put its `x_handle` and `x_related` in that entry; for the main entity, pass the same targeting as outer flags as shown in `comparison.md`. If the engine exits 2 naming an envelope, fix that file or remove that entity's `x_posts` plan entry before retrying; X is then absent for that entity. For an ordinary run, remove `--x-posts` and unset the lane before retrying without the envelope.
+5. **After the run.** The stats line reads "X via X connector" or "X via Grok Bot X". The engine's one receipt line (accepted / dropped counts, on stderr) is diagnostics only: never narrate it in the deliverable (LAW 9).

package/skills/trends/references/hiring-signals.md

@@ -0,0 +1,19 @@
+# Hiring signals
+
+Read when hiring intent selects the jobs lane. Jobs-only planning exceptions apply only within this mode.
+
+### Hiring Signals mode (`--hiring-signals`)
+
+Use `--hiring-signals` when the user asks what a company's jobs page, careers page, LinkedIn jobs, or competitor hiring suggests about strategic focus. This is strongest for early-stage startups and weaker for large companies, where many unrelated roles are hiring noise.
+
+**Hit the company's OWN job board - that is the entire point.** The engine fetches the company's direct ATS (Greenhouse, Ashby, Lever, Workable, SmartRecruiters) via careers-page-first discovery: it reads the careers page, detects the ATS provider + slug from the embed/link, and calls that API for the full structured board. Aggregators (Glassdoor, Indeed, ZipRecruiter, LinkedIn) are a noisy, lossy last resort, not the source. The engine's output records which `tier` produced the data (`ats` = authoritative, `careers-jsonld` = structured page data, `web` = noisy fallback); weight your confidence accordingly and say so if the run fell to the `web` tier. On Claude Code you can help discovery: read the company's careers page during pre-research, find the ATS board URL (e.g. `jobs.ashbyhq.com/{slug}`), and the engine will resolve the rest.
+
+**Weight by novelty and departure-from-baseline, not raw role count.** A single strategic role can outweigh a department's worth of headcount. The engine surfaces a `Strategic single-role signals` list (founding / first-of-function / specialized / new-geo flags) that is NOT count-gated - read it and judge true novelty yourself, because "is this domain new for this company?" needs world knowledge a keyword map cannot encode. Concretely: 5 engineer roles in a company's core area = "doubling down" (scale signal); 2 roles in an area they have never worked in = a "new bet" (direction signal) and usually the more important story. A `Founding {Role}, {New Capability}` posting (e.g. "Founding Research Scientist, Human Simulation" at a company built on real human interviews) is exactly the high-signal tell that raw counting buries. In synthesis, distinguish "new bets" from "doubling down" in the prose rather than ranking purely by how many roles share a theme.
+
+**Output title for a scoped `--hiring-signals` report.** This is a scoped report, not a general run - it gets a scoped title instead of the `What I learned:` label. Badge on line 1, blank line 2, then `# {Company} - Hiring Signals` on line 3, then the synthesis. Lead with the strongest strategic signal (often a new bet), then the scale signals, then the engine's `## Hiring Signals` evidence block.
+
+**`--hiring-signals` is jobs-scoped - do not build a multi-source plan for it.** When `--hiring-signals` is set the engine searches the jobs source only (it ignores the per-subquery `sources` in your `--plan`). So for a pure hiring-signals run, skip the Step 0.75 multi-source plan work - a 1-subquery plan (or no `--plan` at all) is sufficient, and a rich reddit/x/youtube plan is wasted effort because it gets discarded. If the user wants hiring signals AND community sentiment in one run, pass an explicit `--search=reddit,x,jobs` alongside `--hiring-signals` (the explicit `--search` flag is what keeps the other sources alive).
+
+The output must distinguish evidence from interpretation. Good: "3 current roles mention SSO, SOC 2, and procurement workflows, which signals increased enterprise-readiness focus." Bad: "They will ship enterprise SSO next quarter." In standard `/last30days Company` runs, include Hiring Signals only when the engine surfaces a strong signal; otherwise omit the topic entirely.
+
+---

package/skills/trends/references/library-queue.md

@@ -0,0 +1,33 @@
+# Library, feed, and topic queue
+
+Read for library/feed/queue intent before setup or fresh research. The runtime interpreter bootstrap still runs first. These fast paths skip topic/backend preflight, setup, and source research.
+
+**LIBRARY SEARCH FAST PATH — this overrides every research/setup step below.** If the user says “search my library for X”, “have I researched X before?”, or otherwise asks to query prior saved research, do not run WebSearch, setup, topic/backend preflight, or fresh source research. Run:
+
+```bash
+"${LAST30DAYS_PYTHON:-python3}" "${SKILL_DIR}/scripts/last30days.py" library search "${LIBRARY_QUERY}" --save-dir="${LAST30DAYS_MEMORY_DIR}"
+```
+
+Relay the dated, topic-grouped matches. This is deterministic offline FTS over the existing saved-brief scanner plus per-run SQLite store sightings; it does not call a model or the network. If SQLite lacks FTS5, relay the engine's capability error rather than falling through to fresh research.
+
+**LIBRARY FEED FAST PATH — this overrides every research/setup step below.** If the user asks to build, view, refresh, or subscribe to their saved research library/feed, do not run host WebSearch resolution, the first-run setup gate, topic preflight, or source research. Run:
+
+```bash
+"${LAST30DAYS_PYTHON:-python3}" "${SKILL_DIR}/scripts/last30days.py" library feed --save-dir="${LAST30DAYS_MEMORY_DIR}"
+```
+
+Relay the generated local `index.html` and `feed.xml` paths. If the user explicitly asks to publish/share the whole library, explain that `ht-ml.app` pages are public by default and may be crawled or indexed, then follow the existing public-vs-password publishing choice. After consent, add `--publish`; for password protection, supply their unique shared password through `LAST30DAYS_PUBLISH_PASSWORD`, never as a visible command-line flag. Relay the printed library URL and local Atom path, and explain that `feed.xml` becomes subscribable when the output directory is hosted on a static host such as GitHub Pages. Never describe the `ht-ml.app` library URL as an Atom subscription URL, and never add `--publish` merely because the user asked to generate or open a local feed.
+
+**TOPIC QUEUE FAST PATH — this overrides every research/setup step below.** If the user asks "what's in my topic queue", "what should I talk about next", "what topics haven't I covered", "show my content pipeline", "mark <topic> as covered", "I covered X on the podcast", "we published that article", or similar — even cold, with no research run earlier in this session — do not run WebSearch, setup, topic/backend preflight, or fresh source research. Run the read form:
+
+```bash
+"${LAST30DAYS_PYTHON:-python3}" "${SKILL_DIR}/scripts/last30days.py" queue list --save-dir="${LAST30DAYS_MEMORY_DIR}"
+```
+
+or the cover form, for "mark X as covered" phrasing:
+
+```bash
+"${LAST30DAYS_PYTHON:-python3}" "${SKILL_DIR}/scripts/last30days.py" queue cover "<topic name>" --save-dir="${LAST30DAYS_MEMORY_DIR}"
+```
+
+Relay the rendered list (uncovered surfaced topics with domain, surface count, and last-surfaced date) or the cover confirmation. This is deterministic offline SQLite over that save-dir's `research.db`; it does not call a model or the network. Covering requires the exact queued topic name; on an unknown name the engine exits 2 and points at `queue list` - relay that, run `queue list`, and offer the queued names instead of retrying with guesses. An empty queue is a valid answer - suggest a `/last30days trending` or domain discovery run to populate it. Do not treat the topic name or phrase as a fresh research topic and do not fall through to the root's "topic supplied" branch.

package/skills/trends/references/recommendations.md

@@ -0,0 +1,86 @@
+# 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.