yt-briefing 0.11.1 → 0.12.0

package/.claude/skills/yt/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: yt
-description: Briefing from the YouTube channels you follow — the engine sweeps each channel, filters videos in two stages (title, then transcript+content), and lazily yields one video to rate per call. This skill is a thin loop that shows the summary and collects the rating (via AskUserQuestion), which writes durable signal straight into the channel profile. Summaries and the rating question use the language chosen at onboarding.
+description: Briefing from the YouTube channels you follow — the engine sweeps each channel, filters videos in two stages (title, then transcript+content), and lazily yields one video to rate per call. This skill is a thin loop that shows the summary and collects the rating (via AskUserQuestion), which writes durable signal straight into the channel profile. A third option, Research, breaks the loop to dig into the current video's content with the user (full transcript + their question). Summaries and the rating question use the language chosen at onboarding.
 ---
 
 ## How it works
 
-`src/yt-sweep.ts` is **the whole engine**: channel sweep, filters (title filter, then content filter on the transcript via the LLM API), and skip handling — all inside, lazy. The only state it does **not** write is the rating itself — that's `yt-rating.ts` in step D. This skill **does not run filters, read profiles, or format summaries** — it runs the script, pastes the summary, collects the rating.
+`src/yt-sweep.ts` is **the whole engine**: channel sweep, filters (title filter, then content filter on the transcript via the LLM API), and skip handling — all inside, lazy. The only state it does **not** write is the rating itself — that's `yt-rating.ts` in step D. This skill **does not run filters, read profiles, or format summaries** — it runs the script, pastes the summary, collects the rating. The one exception is **Research mode** (below): an explicit user pick that ends the loop and opens the current video's content for discussion.
 
 `data/state.md` is the only persistent cursor. Session state — queue, pending, prefetch, background fill — lives in `data/.cache/` (rebuilt each run, never important to keep). Internals — lazy queue build, filters, summary format, LLM model, transcript fetching, prefetch, proxy — are in `README.md`, not here. No manual pre-flight: the engine self-invalidates a stale queue (new day or `--reset`).
 
@@ -34,22 +34,33 @@ while true:
 - **A.** Take `out.summary` (markdown) and `out.pending` (metadata).
 - **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. _(If the user says "I don't see the summary" — you skipped B.)_
 - **C.** In the same message call `AskUserQuestion` — **1 call, 1 question** (everything in one step), phrased in `output_lang`:
-  - The question (e.g. "Rating?") with two options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles). The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**. There is **no positive rating** — keeping the channel is the implicit positive; you only down-rate noise (`0`) or steer with a comment.
-  - **Other** is the comment / stop channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. Otherwise it is a **comment**: **distill** the user's raw text into a clean, generalizable rule, and infer the rating — clearly negative → `0`, otherwise → `1`.
+  - The question (e.g. "Rating?") with three options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles), **Research** = break the loop and dig into this video's content together. The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**; Research maps to no digit, it exits the loop (see Research mode). There is **no positive rating** — keeping the channel is the implicit positive; you only down-rate noise (`0`) or steer with a comment.
+  - **Other** is the comment / stop / research channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. If it **starts with `?`**, the text after the `?` is a **research question** → Research mode. Otherwise it is a **comment**: **distill** the user's raw text into a clean, generalizable rule, and infer the rating — clearly negative → `0`, otherwise → `1`.
 - **D.** Act on the answer:
   - `stop` / dismissed → **end the loop** (state already on disk).
   - A rating option → `bun run src/yt-rating.ts --rating <1|0>`.
-  - A comment (Other, not `stop`) → `bun run src/yt-rating.ts --rating <inferred 1|0> --comment "<distilled rule>"`.
+  - A comment (Other, not `stop`, not `?…`) → `bun run src/yt-rating.ts --rating <inferred 1|0> --comment "<distilled rule>"`.
+  - **Research** (the option, or a `?…` text) → **break the loop** and switch to **Research mode** below. Skip step E — no more sweep calls this session.
 
   In every non-stop case **pass only the rating (+ comment)**; the script reads channel/id/title/type from `data/.cache/pending.json`. The write is **immediate and durable — no consolidation**: `rating=0` appends to `## Skip titles` (title filter learns to skip such titles from the next run) and a comment appends the rule to `## Notes` (seen by both filters). A neutral `1` writes nothing — it only bumps the state cursor.
 - **E.** Re-run `bun run src/yt-sweep.ts` **bare** (no `--reset` — resumes the same queue; only the loop's first call uses `--reset`). Its JSON becomes the next iteration's `out` — back to the top of the loop.
 
+## Research mode (break the loop and dig in)
+
+The "don't shelve it" path: instead of the briefing landing on a to-do list, the user pulls it apart with you right now — e.g. the channel announces a new tool and the question is whether it beats what their project uses today. Entry: the **Research** option, or an Other text starting with `?`.
+
+1. **Commit first:** `bun run src/yt-rating.ts --rating 1` — engaging with a video is at least neutral, and the bump keeps it from reappearing on the next run. The rating loop is over: no step E, no further sweep calls.
+2. **Get the question.** A `?…` text (or any free text attached to the Research selection) IS the question. If Research was picked bare, ask in `output_lang` what they want to dig into.
+3. **Pull the full transcript** — the summary is too lossy to research from: `bun run src/yt-transcript.ts <videoId> --lang auto`, videoId from `out.pending` (or `data/.cache/pending.json`). The transcript arrives as the tool result — work from it there, never paste it into chat. Non-zero exit (`1` no subtitles / `2` IP-blocked / `3` tooling, reason on stderr) → tell the user and work from the summary instead.
+4. **Work the question with the user, grounded.** The transcript is the source for what the video *claims*; keep "the video claims X" separate from what you verify yourself. Use whatever tools the question needs — read the user's project when they ask "would this fit project xyz", search the web for docs / changelogs / pricing. It is a conversation, not a one-shot report: answer, then iterate until the user is done.
+5. **Closing.** `data/.cache/pending.json` is still on disk, so a verdict can still be recorded: turned out to be hype → `bun run src/yt-rating.ts --rating 0`; a durable channel preference surfaced → `--rating 1 --comment "<distilled rule>"` (the re-bump is a no-op). Mention that `/yt` resumes the queue where it left off — re-enter the rating loop (re-run the engine **bare**) only if the user asks.
+
 ## No consolidation
 
 There is no post-loop step. Each rating is **durable immediately**: `yt-rating.ts` writes `rating=0` straight to `## Skip titles` and a comment straight to `## Notes` (FIFO-capped, de-duplicated). `rating=1` only bumps the cursor. The title filter reads those sections live, so the signal takes effect on the very next sweep — nothing to flush, batch, or trigger.
 
 ## Rules
 
-- **Language:** question text, option descriptions, and loop messages follow `output_lang`; the two rating **labels** are `OK` / `Weak`. Summaries are written in `output_lang` by the content-filter prompt in the engine — not here.
-- **Transcripts:** never paste a raw transcript into chat; the summary is the artifact.
+- **Language:** question text, option descriptions, and loop messages follow `output_lang`; the three option **labels** are `OK` / `Weak` / `Research`. Summaries are written in `output_lang` by the content-filter prompt in the engine — not here. Research mode converses in `output_lang` unless the user switches.
+- **Transcripts:** never paste a raw transcript into chat; the summary is the artifact. In research mode, quote only the short passages you need.
 - **Resuming:** the skill can be re-run any time — `data/state.md` is the source of truth, so a re-run always skips what's already rated. A queue from a previous day self-invalidates; the loop's first call passes `--reset` to also force a **same-day** rebuild, catching videos published since that morning's queue.

package/README.md

@@ -118,6 +118,16 @@ it to go deeper, lower it for a quicker pass:
 /yt-search @betterstack which terminal --top 5
 ```
 
+## Don't shelve it — research it
+
+Tech channels announce something new every week, and the usual fate is "looks interesting" →
+to-do list → never. So the rating popup has a third option next to OK/Weak: **Research**. Pick
+it — or type `? your question` straight into the comment box — and the loop ends there: the
+agent pulls that video's full transcript and works your question with you. Against your own
+codebase if you ask "would this fit my project", against the web if the claims need checking —
+a quick feedback loop instead of a shelf. The video is marked as seen, and the next `/yt`
+resumes the queue right where you broke off.
+
 ## Run it
 
 Open your project in Claude Code or Cursor and run `/yt`. If it's not listed, start a fresh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "A self-learning YouTube briefing engine: it sweeps the channels you follow, filters noise in two stages (title, then transcript), summarizes the rest in your language, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {
@@ -50,9 +50,10 @@
     "dotenv": "^16.6.1"
   },
   "devDependencies": {
+    "@socketsecurity/bun-security-scanner": "^1.1.2",
+    "@types/bun": "^1.3.14",
     "@types/node": "^22",
     "typescript": "^5.7",
-    "@types/bun": "latest",
     "vitest": "^3"
   }
 }