docent-explain

docent-explain — the end-to-end docent skill

You are running the entire docent cascade against a subject the user just named: survey → treatment → spec → tts → clips → render → open. This is the flagship skill; the other docent skills are sub-steps of this one. Reach for those only when the user explicitly wants to pause between stages.

Arguments

/docent-explain <subject> [--mode pr|ar|ex] [--subsystem X] [--pr N] [--id X] [--scale S] [--no-open]

• <subject> — a repo path, a github URL, a single file, a wiki directory, a blog URL, or an essay. The first positional is the subject.
• --mode — pr (PR review), ar (architecture review), ex (explainer). Inferred from the subject when omitted.
• --subsystem X — for ar, scope to one subsystem.
• --pr N — for pr, the pull-request number.
• --id X — override the auto-derived film id.
• --scale S — render scale. Default 1. Pass 0.5 for fast turnarounds.
• --no-open — render without opening the result in the system player.

What to do

1. Pre-flight. Confirm the environment is ready by checking that the agent CLI (claude or codex), bun, and ffmpeg are on PATH. If anything obvious is missing, suggest /docent-doctor and stop. Do not run doctor here implicitly — it has its own skill.

2. Find the right surface, then survey. The fetcher behind docent survey does one thing — fetch the URL you give it and report what came back. It does not know that arXiv's /abs/ is a stub or that a paper's full text lives at /html/ or /pdf/. That intelligence is yours — you are the agent. Walk the surfaces deliberately:

   • If the user passed a URL that looks like an abstract, stub, or landing page (arxiv.org/abs/, a paper's homepage, a wiki article's "main" page), assume there is a richer surface and try it first. Common patterns worth trying in order:
     • arxiv.org/abs/<id> → try arxiv.org/html/<id> (rendered LaTeX, ~40k chars) then arxiv.org/pdf/<id> (PDF via pdftotext).
     • biorxiv.org/content/<doi> → try the same URL with .full appended.
     • A paper homepage → look for a "PDF" or "Full text" link and use that URL.
   • Always do an exploratory fetch first.

     docent survey <url> --mode ex --id <slug>
     

     The fetcher writes analysis/<id>.source.md and logs a character count. If the count is below ~5 000 chars and you have an alternative surface, stop the in-progress survey, swap the URL, and re-run. Surveying a stub returns a film about a stub.
   • PDFs work natively. Pass https://…/whatever.pdf directly; the engine pipes it through pdftotext. No special invocation.
   • When you've exhausted surfaces and the source is still thin, don't paper over it — say so in the survey explicitly and narrow the film's claim to what the text actually supports.