| name | youtube-cumulative-research |
| description | Build or resume a source-backed YouTube research session that checks the local yt-insights corpus first, asks before discovery and acquisition, grows the corpus only with explicit approval, reassesses coverage, and optionally exports a dossier. Use for evolving research topics, freshness checks, or research dossiers. Do not use for a simple read-only corpus lookup. |
Run cumulative YouTube research
Run this workflow in the main session because discovery and approved acquisition may use the network and write local source files. Use the packaged yt-insights research CLI as the source of truth. The read-only MCP may help with a separate local lookup, but never use it for a research state transition or mutation.
Start or resume
- Start with
yt-insights research start "TOPIC" --query "QUERY" --freshness-profile standard --json. Use one to eight explicit queries. Do not add hidden query expansion.
- Resume with
yt-insights research status SESSION_ID --json. Preserve the returned session ID and revision exactly.
- Treat invalid JSON or an unknown schema as unverified state. Stop, show a bounded error, and do not infer a command, revision, candidate, or result.
- For every command after the first response, use the latest revision returned by the previous JSON response. Generate a fresh idempotency key for every distinct mutation. Reuse a key only to replay the exact same request with the same session, revision, action, and payload.
Present the recorded queries, freshness profile, coverage counts, newest relevant source date, last successful discovery date, unknown dates, and explicit coverage limits. Keep claims tied to stored evidence, source hashes, and timestamped URLs.
Required human decisions
Interpret required_user_action literally:
- For
confirm_sufficiency_or_refresh, ask whether the current evidence is sufficient or whether the user wants newer YouTube candidates. Record the answer with yt-insights research decide SESSION_ID sufficient|refresh --revision REVISION --idempotency-key KEY --json.
- A
refresh decision authorizes discovery only. Run yt-insights research discover SESSION_ID --revision REVISION --json, then use yt-insights research candidates SESSION_ID --json to present at most ten candidates with ID, title, channel, publication date, matched query, and URL.
- For
approve_candidates_or_cancel, ask the user to select one to five exact candidate IDs or cancel. Never approve candidates on the user's behalf. Repeat only the selected IDs, unchanged, in yt-insights research approve SESSION_ID VIDEO_ID... --revision REVISION --idempotency-key KEY --json. Use yt-insights research cancel SESSION_ID --revision REVISION --idempotency-key KEY --json only when the user chooses to cancel.
After approval, acquire only the exact approved video IDs with yt-insights research acquire SESSION_ID --revision REVISION --idempotency-key KEY --json. Do not substitute a missing video, expand to a playlist or channel, or add related videos. Present per-video outcomes, the refreshed assessment, and the sufficiency question again.
When acquisition_history reports a latest attempt as failed_retryable, present the successful and failed video outcomes, then ask the sufficiency question. Offer yt-insights research retry SESSION_ID --revision REVISION --idempotency-key KEY --json as an explicit alternative that retries only failed video IDs. Do not retry automatically: the user may instead accept the partial evidence with decide ... sufficient or request fresh discovery with decide ... refresh. For every other retryable stage, use research retry only for the transition reported by the session. Never replay a committed decision or a successful acquisition.
Output choice
After sufficiency is confirmed, ask whether the user wants a dossier, an article draft, a corpus export, both, or nothing else.
- Export deterministic evidence with
yt-insights research export SESSION_ID --output ABSOLUTE_DIRECTORY --json.
- Draft prose only after that explicit choice. Keep model synthesis separate from YouTube source evidence and state unresolved questions and coverage limits.
- A transcript corpus export uses the existing exact-video export workflow and an explicit destination. Generated dossiers and prose never become source passages.
Fail closed
- Missing session: stop and ask for a valid session ID or permission to start a new session.
- Stale revision: run
yt-insights research status SESSION_ID --json, present the changed state, and ask for the needed decision again. Do not replay the rejected command.
- Unavailable network or provider: preserve the session, report the bounded failure, and stop after the failed call. Retry only when the user requests it.
- If the relevance gate is
FAIL or UNKNOWN, report that retrieval quality and global activation are not validated. The exact local workflow remains available, but do not claim the skill is globally activated or that evidence quality passed its gate.
- Candidate or acquisition failure: preserve recorded outcomes and never choose a replacement automatically.
Do not install or modify global Claude Code or Codex configuration through this skill. Global activation requires a separately approved candidate and fresh-session verification.
