luckiest-co 1.0.47 → 1.0.49

package/skills/youtube-planner/references/plan-template.md

@@ -0,0 +1,57 @@
+# youtube-plan.md template
+
+Copy this shape. Keep it under about 120 lines. Every number carries its source.
+
+```markdown
+# <working title>
+
+Audience: <who> · Goal: <subscribers | signups | authority | format test> · Channel: <url or none>
+
+## Scores
+
+| Stage | Score | Weak link |
+|---|---|---|
+| Idea | n/10 | |
+| Packaging | n/10 | |
+| Hook | n/10 | |
+| Body | n/10 | |
+| Readout | n/10 | |
+
+## 1. Idea
+Topic: <chosen topic>, bundled as <bundle or none>
+Floor <n> · Ceiling p90 <n> / max <n> · Fresh <n>% · Missing <n> of <n>
+Source: floor_ceiling.py on <date>, or user-supplied
+Dropped: <topic>: <reason>
+
+## 2. Packaging
+| Title | Pattern | Why it works here | Thumbnail |
+|---|---|---|---|
+Pick: <title + thumbnail>
+
+## 3. Hook
+- Promise:
+- Proof:
+- Plan:
+- Persona:
+<spoken hook lines>
+
+## 4. Body
+Must be true for the title to be true:
+1. <item>
+   - <sub-item>
+First value lands at: <m:ss>
+Beats expectation by: <item>
+
+## 5. Readout
+Review on: <date>
+| Signal | Good if | Points to |
+|---|---|---|
+| Positive comments per 1k views | | Idea / Body |
+| Likes per view | | Body |
+| Subs per view | | Persona |
+| CTR | | Packaging |
+| Retention drops | | Hook / that moment |
+
+## Next
+<weakest stage>: <one action>
+```

package/skills/youtube-planner/references/stages.md

@@ -0,0 +1,119 @@
+# Stage rubrics and examples
+
+Score each stage from 1 to 10. A 7 means the stage has no known weak link. Below
+7, name the weak link and the fix.
+
+## 1. Idea
+
+| Score | Means |
+|---|---|
+| 9-10 | Floor worth the goal, ceiling at least 5x the floor, most top results under 12 months old, and a bundle that lifts the ceiling without losing the floor |
+| 7-8 | Floor worth the goal, demand current, no bundle or a weak one |
+| 4-6 | Demand real but stale, or the floor is too low for the goal |
+| 1-3 | Topic chosen from what the audience "needs" with no viewing evidence |
+
+Reading the script output:
+- **Floor** = median views of the results. This is what a decent video should expect.
+- **Ceiling** = the p90 and max views. This is what the best video can reach.
+- **Fresh share** = the share of results uploaded in the last 12 months. Under
+  about 30% suggests the interest has moved on.
+- **Missing** = results with no view count or date. Do not guess them. If more
+  than a third are missing, rerun with a larger `--limit` or ask the user for counts.
+- Treat search results as a sample of what YouTube surfaces, not the whole niche.
+
+Bundling demand, by example: a narrow how-to ("lead generation strategy") gets
+paired with a name the same audience already follows ("<known founder>'s lead
+generation strategy"). It reaches both the people searching the topic and the
+people who follow the name. The bundle has to be true. The video must actually
+cover that person's method from public sources.
+
+Real views check: a video with very high views but almost no comments or likes,
+or a channel whose other videos get a tiny fraction of that, is a sign of
+bought or bot views. Leave it out of the floor.
+
+Own-channel outliers: when the user gave a channel, compare each candidate's
+top videos with their channel's own median. A video at 5x its channel's median
+says more than a big channel's ordinary video.
+
+## 2. Packaging
+
+| Score | Means |
+|---|---|
+| 9-10 | A cross-niche pattern with a stated reason, a thumbnail readable at phone size, title and thumbnail that do not repeat each other, a promise the outline keeps |
+| 7-8 | All of the above, with a weaker reason or a busier thumbnail |
+| 4-6 | Copies one outlier, or the title and thumbnail say the same thing |
+| 1-3 | Clickbait the body cannot pay off |
+
+Framings that tend to win across niches (always state why for this audience):
+- **"The new rules of X"**: "rules" means getting this wrong costs you, and "new"
+  means what you know may be out of date. It only works if something really changed.
+- **"I tried X for N days"**: a concrete test with an unknown result.
+- **"X vs Y"**: a choice the viewer is already weighing.
+- **"Why X is failing" or "Stop doing X"**: a threat to something they already do.
+- **"How <known person> does X"**: authority plus a bundle of demand.
+
+Overfitting check: before using a framing, write down why it worked where you
+saw it, and whether the same reason holds for this audience. If you cannot say
+why, do not use it.
+
+Thumbnail jobs:
+1. Stand out in a feed of about 20 videos (a face, contrast, one focal object).
+2. Be understood in under a second (2 to 3 elements, at most 3 words).
+3. Open a question that the title closes just enough to make the viewer click.
+
+## 3. Hook
+
+| Score | Means |
+|---|---|
+| 9-10 | All four Ps answered in under 30 seconds, proof is specific and true, plan names every step |
+| 7-8 | All four Ps, with vague proof or plan |
+| 4-6 | Missing one P |
+| 1-3 | A tease with no promise or plan |
+
+Persona matters most when the packaging could pull in two audiences. Say
+plainly who it is for, so the wrong viewers leave early and the right ones stay.
+
+## 4. Body
+
+| Score | Means |
+|---|---|
+| 9-10 | Every outline item traces to the title's promise, first value in the first minute, nothing unrelated, at least one item that beats the expectation, and each section runs a full story loop that reopens before it closes |
+| 7-8 | Every item traces to the promise, value arrives late |
+| 4-6 | Some sections serve the creator, not the promise |
+| 1-3 | An info dump of everything the creator knows |
+
+Breakdown example for the title "The most useful YouTube training you will
+watch": for it to be true, it must cover ideas, packaging, the video itself,
+and the results, with no gap between them. Each of those then breaks down
+again, for example ideas into finding demand, the floor and ceiling, and
+raising the ceiling. Each leaf becomes one section, and each section is a
+requirement.
+
+Story loop check, per section:
+- No stakes (nobody to root for, nothing to lose): the viewer has no reason to care. Add a person and a risk.
+- No open question: the section explains without making anyone wonder. Write the question the viewer should be asking.
+- No turn: the answer is the one everyone expected. Find what the audience usually believes, then show where it breaks.
+- No reopen: the section ends flat and viewers leave. End each section on the next question.
+
+Retention is not the goal. A long training with low average view duration can
+still win if the people who watch it get more than they expected. They comment,
+subscribe, and buy, and YouTube shows the video to more people like them.
+
+## 5. Readout
+
+| Score | Means |
+|---|---|
+| 9-10 | The satisfaction signals and their thresholds are written down before publishing, each metric maps to a stage to inspect, and a review date is set |
+| 7-8 | Signals listed, no thresholds or date |
+| 4-6 | Only views and CTR |
+| 1-3 | No plan to read the results |
+
+Signal to stage map:
+- Low CTR: inspect packaging (stage 2). Low CTR alone is not proof. Hits have
+  run at 2 to 3%.
+- Early retention drop (first 30 seconds): inspect the hook (stage 3).
+- A cliff later: inspect that moment in the body (stage 4), for example a hard
+  call to action. Trim it after publishing if needed.
+- Views flat but comments glowing: inspect the idea (stage 1). The ceiling may be low.
+- Many negative or "this isn't what the title said" comments: the promise and
+  the body do not match (stages 2 and 4).

package/skills/youtube-planner/scripts/floor_ceiling.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Floor and ceiling views for a YouTube topic, from public search results.
+
+Usage:
+  floor_ceiling.py '<topic>' [--limit 30] [--json]
+  floor_ceiling.py --self-test
+
+Floor = median views. Ceiling = p90 and max views. Fresh = share uploaded in the
+last 12 months. Entries with no view count or date are counted, never guessed.
+Stdlib only. Calls yt-dlp as an external tool, with no shell.
+"""
+import argparse
+import datetime as dt
+import json
+import math
+import shutil
+import statistics
+import subprocess
+import sys
+
+FRESH_DAYS = 365
+
+
+def percentile(sorted_vals, p):
+    # ponytail: nearest-rank percentile, fine for 10-50 samples
+    if not sorted_vals:
+        return None
+    k = max(0, min(len(sorted_vals) - 1, math.ceil(p / 100 * len(sorted_vals)) - 1))
+    return sorted_vals[k]
+
+
+def summarize(entries, today):
+    views = sorted(e["view_count"] for e in entries if isinstance(e.get("view_count"), int))
+    dated = [e for e in entries if e.get("upload_date")]
+    fresh = 0
+    for e in dated:
+        d = dt.datetime.strptime(e["upload_date"], "%Y%m%d").date()
+        if (today - d).days <= FRESH_DAYS:
+            fresh += 1
+    top = sorted((e for e in entries if isinstance(e.get("view_count"), int)),
+                 key=lambda e: -e["view_count"])[:5]
+    return {
+        "results": len(entries),
+        "with_views": len(views),
+        "missing_views": len(entries) - len(views),
+        "missing_dates": len(entries) - len(dated),
+        "floor_median": int(statistics.median(views)) if views else None,
+        "ceiling_p90": percentile(views, 90),
+        "ceiling_max": views[-1] if views else None,
+        "fresh_share": round(fresh / len(dated), 2) if dated else None,
+        "top": [{"views": e["view_count"], "date": e.get("upload_date"),
+                 "channel": e.get("channel"), "title": e.get("title")} for e in top],
+    }
+
+
+def search(topic, limit):
+    if not shutil.which("yt-dlp"):
+        sys.exit("yt-dlp not found. Install it, or ask the user for view counts.")
+    # ponytail: full metadata per result is slow (~1s each), flat-playlist lacks dates
+    cmd = ["yt-dlp", "--dump-json", "--skip-download", "--no-warnings",
+           "--ignore-errors", f"ytsearch{limit}:{topic}"]
+    out = subprocess.run(cmd, capture_output=True, text=True, timeout=600).stdout
+    entries = []
+    for line in out.splitlines():
+        try:
+            d = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        entries.append({k: d.get(k) for k in ("view_count", "upload_date", "channel", "title")})
+    return entries
+
+
+def fmt(n):
+    return "unknown" if n is None else f"{n:,}"
+
+
+def report(topic, s):
+    print(f"Topic: {topic}")
+    print(f"Results: {s['results']} (missing views {s['missing_views']}, missing dates {s['missing_dates']})")
+    print(f"Floor (median): {fmt(s['floor_median'])}")
+    print(f"Ceiling: p90 {fmt(s['ceiling_p90'])} / max {fmt(s['ceiling_max'])}")
+    fs = s["fresh_share"]
+    print(f"Fresh (last 12 months): {'unknown' if fs is None else f'{int(fs * 100)}%'}")
+    for t in s["top"]:
+        print(f"  {t['views']:>12,}  {t['date'] or '????????'}  {(t['channel'] or '')[:20]:<20}  {(t['title'] or '')[:60]}")
+    if s["results"] and s["missing_views"] > s["results"] / 3:
+        print("Note: over a third of results lack views. Rerun with a larger --limit or use user counts.")
+
+
+def self_test():
+    today = dt.date(2026, 10, 16)
+    sample = [
+        {"view_count": 1000, "upload_date": "20260901"},
+        {"view_count": 5000, "upload_date": "20250101"},
+        {"view_count": 20000, "upload_date": "20260501"},
+        {"view_count": 300000, "upload_date": "20260101"},
+        {"view_count": None, "upload_date": "20260801"},
+        {"view_count": 8000, "upload_date": None},
+    ]
+    s = summarize(sample, today)
+    assert s["results"] == 6 and s["with_views"] == 5
+    assert s["missing_views"] == 1 and s["missing_dates"] == 1
+    assert s["floor_median"] == 8000, s
+    assert s["ceiling_max"] == 300000 and s["ceiling_p90"] == 300000
+    assert s["fresh_share"] == 0.8, s  # 4 of 5 dated are within 365 days
+    assert s["top"][0]["views"] == 300000
+    empty = summarize([], today)
+    assert empty["floor_median"] is None and empty["fresh_share"] is None
+    print("self-test ok")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("topic", nargs="?")
+    ap.add_argument("--limit", type=int, default=30)
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--self-test", action="store_true")
+    a = ap.parse_args()
+    if a.self_test:
+        return self_test()
+    if not a.topic:
+        ap.error("topic is required")
+    a.limit = max(1, min(a.limit, 100))
+    s = summarize(search(a.topic, a.limit), dt.date.today())
+    if a.json:
+        print(json.dumps({"topic": a.topic, **s}, indent=2))
+    else:
+        report(a.topic, s)
+
+
+if __name__ == "__main__":
+    main()

package/skills/coder-brainstorming/spec-document-reviewer-prompt.md

@@ -1,49 +0,0 @@
-# Spec Document Reviewer Prompt Template
-
-Use this template when dispatching a spec document reviewer subagent.
-
-**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
-
-**Dispatch after:** Spec document is written to docs/luckiest-coder/specs/
-
-```
-Subagent (general-purpose):
-  description: "Review spec document"
-  prompt: |
-    You are a spec document reviewer. Verify this spec is complete and ready for planning.
-
-    **Spec to review:** [SPEC_FILE_PATH]
-
-    ## What to Check
-
-    | Category | What to Look For |
-    |----------|------------------|
-    | Completeness | TODOs, placeholders, "TBD", incomplete sections |
-    | Consistency | Internal contradictions, conflicting requirements |
-    | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
-    | Scope | Focused enough for a single plan — not covering multiple independent subsystems |
-    | YAGNI | Unrequested features, over-engineering |
-
-    ## Calibration
-
-    **Only flag issues that would cause real problems during implementation planning.**
-    A missing section, a contradiction, or a requirement so ambiguous it could be
-    interpreted two different ways — those are issues. Minor wording improvements,
-    stylistic preferences, and "sections less detailed than others" are not.
-
-    Approve unless there are serious gaps that would lead to a flawed plan.
-
-    ## Output Format
-
-    ## Spec Review
-
-    **Status:** Approved | Issues Found
-
-    **Issues (if any):**
-    - [Section X]: [specific issue] - [why it matters for planning]
-
-    **Recommendations (advisory, do not block approval):**
-    - [suggestions for improvement]
-```
-
-**Reviewer returns:** Status, Issues (if any), Recommendations

package/skills/trends/scripts/lib/reddit_rss.py

@@ -1,224 +0,0 @@
-"""Keyless Reddit discovery via public RSS/Atom feeds.
-
-Reddit's ``.json`` search endpoints now return HTTP 403 (shreddit anti-bot).
-RSS feeds still serve HTTP 200 with no API key, so this module uses them for
-post discovery, replacing ``reddit_public.search`` as the free search path.
-
-Two feed families are combined and deduped:
-- search:  /search.rss?q=... and /r/{sub}/search.rss?q=...&restrict_sr=on
-- listing: /r/{sub}/{top,hot}.rss?t=month
-
-RSS entries carry no engagement score, so ``score``/``num_comments`` start at 0
-and are backfilled during shreddit enrichment (see reddit_shreddit.py). Output
-dicts match the normalized shape emitted by ``reddit_public._parse_posts`` so
-downstream code (pipeline, renderer) is unaffected.
-"""
-
-import sys
-import xml.etree.ElementTree as ET
-from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-from urllib.parse import quote_plus
-
-from . import http
-from .relevance import token_overlap_relevance
-
-ATOM = "{http://www.w3.org/2005/Atom}"
-
-# Mirror reddit_public depth-aware limits so the two free paths behave alike.
-DEPTH_LIMITS = {
-    "quick": 10,
-    "default": 25,
-    "deep": 50,
-}
-
-# Listing sorts pulled per subreddit (in addition to search), for volume.
-LISTING_SORTS = {
-    "quick": ["top"],
-    "default": ["top", "hot"],
-    "deep": ["top", "hot", "new"],
-}
-
-MAX_WORKERS = 4
-FEED_TIMEOUT = 15
-
-
-def _log(msg: str) -> None:
-    sys.stderr.write(f"[RedditRSS] {msg}\n")
-    sys.stderr.flush()
-
-
-def _iso_to_date(value: Optional[str]) -> Optional[str]:
-    """Parse an ISO-8601 timestamp (e.g. 2026-05-20T18:48:31+00:00) to YYYY-MM-DD."""
-    if not value:
-        return None
-    try:
-        dt = datetime.fromisoformat(value.strip())
-        return dt.date().isoformat()
-    except (ValueError, TypeError):
-        return None
-
-
-def _iso_to_epoch(value: Optional[str]) -> Optional[float]:
-    if not value:
-        return None
-    try:
-        dt = datetime.fromisoformat(value.strip())
-        if dt.tzinfo is None:
-            dt = dt.replace(tzinfo=timezone.utc)
-        return dt.timestamp()
-    except (ValueError, TypeError):
-        return None
-
-
-def _subreddit_from(category: str, url: str) -> str:
-    """Derive subreddit name from the entry category or, failing that, the URL."""
-    if category:
-        return category
-    # URL form: https://www.reddit.com/r/{sub}/comments/{id}/...
-    parts = url.split("/r/", 1)
-    if len(parts) == 2:
-        return parts[1].split("/", 1)[0]
-    return ""
-
-
-def _parse_feed(xml_text: str, query: str = "") -> List[Dict[str, Any]]:
-    """Parse an Atom feed string into normalized post dicts. Never raises."""
-    if not xml_text:
-        return []
-    try:
-        root = ET.fromstring(xml_text)
-    except ET.ParseError as e:
-        _log(f"feed parse error: {e}")
-        return []
-
-    posts: List[Dict[str, Any]] = []
-    for entry in root.iter(f"{ATOM}entry"):
-        link_el = entry.find(f"{ATOM}link")
-        url = link_el.get("href", "").strip() if link_el is not None else ""
-        if not url or "/comments/" not in url:
-            continue
-
-        title_el = entry.find(f"{ATOM}title")
-        title = (title_el.text or "").strip() if title_el is not None else ""
-
-        author = ""
-        author_el = entry.find(f"{ATOM}author/{ATOM}name")
-        if author_el is not None and author_el.text:
-            author = author_el.text.strip().removeprefix("/u/").removeprefix("u/")
-        if author in ("[deleted]", "[removed]", ""):
-            author = "[deleted]"
-
-        cat_el = entry.find(f"{ATOM}category")
-        category = cat_el.get("term", "").strip() if cat_el is not None else ""
-        subreddit = _subreddit_from(category, url)
-
-        updated_el = entry.find(f"{ATOM}updated")
-        updated = (updated_el.text or "").strip() if updated_el is not None else ""
-
-        content_el = entry.find(f"{ATOM}content")
-        selftext = ""
-        if content_el is not None and content_el.text:
-            # Strip the simplest HTML; renderer only needs an excerpt.
-            import re as _re
-            selftext = _re.sub(r"<[^>]+>", " ", content_el.text)
-            selftext = _re.sub(r"\s+", " ", selftext).strip()[:500]
-
-        relevance = round(token_overlap_relevance(query, title), 3) if query else 0.0
-
-        posts.append({
-            "id": "",  # assigned after dedup
-            "title": title,
-            "url": url,
-            "score": 0,            # backfilled by shreddit enrichment
-            "num_comments": 0,     # backfilled by shreddit enrichment
-            "subreddit": subreddit,
-            "created_utc": _iso_to_epoch(updated),
-            "author": author,
-            "selftext": selftext,
-            "date": _iso_to_date(updated),
-            "engagement": {
-                "score": 0,
-                "num_comments": 0,
-                "upvote_ratio": None,
-            },
-            "relevance": relevance,
-            "why_relevant": "Reddit RSS",
-            "metadata": {},
-        })
-
-    return posts
-
-
-def _build_urls(query: str, depth: str, subreddits: Optional[List[str]]) -> List[str]:
-    """Build the keyless RSS feed URLs to fan out across."""
-    q = quote_plus(query)
-    urls: List[str] = [
-        f"https://www.reddit.com/search.rss?q={q}&sort=relevance&t=month"
-    ]
-    for raw_sub in (subreddits or []):
-        sub = raw_sub.removeprefix("r/").strip()
-        if not sub:
-            continue
-        urls.append(
-            f"https://www.reddit.com/r/{sub}/search.rss"
-            f"?q={q}&restrict_sr=on&sort=relevance&t=month"
-        )
-        for sort in LISTING_SORTS.get(depth, LISTING_SORTS["default"]):
-            urls.append(f"https://www.reddit.com/r/{sub}/{sort}.rss?t=month")
-    return urls
-
-
-def _fetch_feed(url: str, query: str) -> List[Dict[str, Any]]:
-    """Fetch and parse one feed. Never raises."""
-    try:
-        text = http.reddit_keyless_get_text(url, timeout=FEED_TIMEOUT, accept="application/atom+xml")
-        return _parse_feed(text, query) if text else []
-    except Exception as e:  # defensive: a single bad feed must not sink the run
-        _log(f"feed fetch failed for {url}: {e}")
-        return []
-
-
-def search_rss(
-    query: str,
-    depth: str = "default",
-    subreddits: Optional[List[str]] = None,
-) -> List[Dict[str, Any]]:
-    """Discover Reddit posts for a query via keyless RSS feeds.
-
-    Args:
-        query: Search query string
-        depth: 'quick', 'default', or 'deep' — controls result limit and feeds
-        subreddits: Optional pre-resolved subreddit names (without r/) to target
-
-    Returns:
-        List of normalized post dicts (deduped by URL, capped by depth),
-        with placeholder scores to be backfilled during enrichment.
-        Empty list on any failure.
-    """
-    limit = DEPTH_LIMITS.get(depth, DEPTH_LIMITS["default"])
-    urls = _build_urls(query, depth, subreddits)
-
-    all_posts: List[Dict[str, Any]] = []
-    workers = min(MAX_WORKERS, len(urls)) or 1
-    with ThreadPoolExecutor(max_workers=workers) as executor:
-        futures = {executor.submit(_fetch_feed, url, query): url for url in urls}
-        for future in futures:
-            try:
-                all_posts.extend(future.result(timeout=FEED_TIMEOUT + 5))
-            except (Exception, FuturesTimeoutError) as e:
-                _log(f"feed future failed: {e}")
-
-    # Dedupe by URL (first occurrence wins).
-    seen: set = set()
-    unique: List[Dict[str, Any]] = []
-    for post in all_posts:
-        if post["url"] not in seen:
-            seen.add(post["url"])
-            unique.append(post)
-
-    for i, post in enumerate(unique):
-        post["id"] = f"R{i + 1}"
-
-    return unique[:limit]