Docent ar

Skill benelser/docent/packages/agent/skills/docent-ar

Point it at anything — a codebase, a PR, an essay, a paper, a URL — and get back a narrated, animated film that argues for what it explains. A closed grammar of explanation rendered by a coding agent, judged before it ships.

Install

npx -y skills add benelser/docent --skill docent-ar

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Render an architecture-review film — a whole system, or one named subsystem, at depth (components, how control and data flow, the idioms, the failure modes, and the trade-offs). Use when the user says "/docent-ar <repo>", asks to "review the architecture of X", "explain how X works as a film", or hands over a repo URL expecting a system-level explainer film.

SKILL.md

7.3 KB, as published. Nobody here has run it

docent-ar — the architecture-review film

You are running the entire docent cascade in architecture-review mode against a repository the user named: survey → treatment → spec → tts → clips → render → open. The output is one MP4 that explains the system the way a distinguished engineer would: the components, the flow, the idioms, the failure modes, the trade-offs, with a verdict.

Arguments

/docent-ar <repo> [--subsystem X] [--id X] [--scale S] [--no-open]

<repo> — a local repo path, a GitHub URL, or the bare owner/name form.
--subsystem X — scope the review to one subsystem. The survey resolves this to a concrete code boundary (a directory, a package, a set of files) before starting.
--id X — override the auto-derived film id (default: <repo-name>).
--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

Pre-flight. Confirm bun, ffmpeg, and the agent CLI are on PATH. If anything obvious is missing, suggest /docent-doctor and stop.
Survey — architecture mode:
```
bun packages/agent/scripts/survey.ts <repo> --mode ar [--subsystem X] [--id X]
```
The survey lands at analysis/<id>.md. When a subsystem is named, section 0 of the survey template resolves it to concrete files first — surface that boundary to the user before moving on. The survey's job here is to interrogate the system: not a tour that admires it, but a depth-first reading that names the trade-off and the failure mode.

Before moving on, surface the lineage sections to the user:
- § 1.5 The premise — one paragraph: the bet this system makes about the world.
- § 1.6 The novelty — one sentence: the line this system draws somewhere a prior system did not.
- § 1.7 Prior and similar works — the 2-4 named, dated systems the film will compare against and the dimension on which each diverges. Confirm with the user that the named lineage is the right lineage before moving on — the rest of the cascade reads from it.
Commit to a style. Before the treatment, decide the visual register the film renders in:
```
bun run docent style recommend <id>
```
For architecture-review films the recommender will return engineering when the subject is a code repository (most ARs) and paper when the subject is a research-shaped artefact. Take the recommendation unless the survey surfaces a specific reason to override. Surface the choice in one line — "rendering in engineering — system-level architecture review; rationale: ..." — and move on. The spec compilation reads this off the survey's "Style commitment" section and pins it as the spec's style: {preset, intent, rationale} field. The depth-review judge fails the style-committed dimension if the spec ships without it.

3b. Commit to a scene set. Same shape as the style commitment, one layer down — the cognitive moves the film will make.

bun run docent scene-fit recommend <id>

The recommender reads the survey and prints the top scene types with rationales tying each to a specific survey finding. Architecture films almost always want prior-art (the lineage from § 1.7), structure (the components), and either tension (the trade-off the design made) or causal-loop / mechanism (when the dynamics matter more than the layout). If the recommender returns warningOnDefault: true, the survey collapsed to the default rut — re-read § 1.5/1.6 and ask whether the system's bet is genuinely about components or about something specific (feedback dynamics → causal-loop; a working motion → mechanism; a regional topology → map). Pin the chosen scene set in the survey's "Scene-set commitment" section.

Treatment.
```
bun packages/agent/scripts/treatment.ts <id>
```
Writes treatments/<id>.md. Print the Angle line so the user sees the through-line you committed to.
Spec — and interrogate it.
```
bun packages/agent/scripts/treatment.ts <id> --to-spec
bun packages/agent/scripts/flywheel.ts <id> --max-rounds 2
```
The first compiles the treatment into films/<id>.json. The second is mandatory — review runs the adversarial judge → revise → re-judge loop bounded to two rounds. On the corpus this reliably lifts a first-draft spec by ~7 points / 30 — the difference between an architecture film that passes the depth contract and one that does not. Surface the verdict score and the weakest dimension (often trade-off, the-numbers, or novelty-named / prior-art-honest for AR films) before rendering. If review exhausts its round budget, stop and ask — do not ship a film the judge rejected.

Before rendering, surface the Prior Art table and the novelty dimension to the user. Open films/<id>.json, find the type: 'prior-art' scene, and tell the user, in one line:

"This film argues that <subject>'s novelty is <dimension label>: <novelty.statement>. The lineage: <system labels>. Confirm before render."

Wait for confirmation. A user who pushes back on the novelty dimension is steering the film's spine — do not render past their objection.
Render.
```
bun run docent build <id> --scale 1
```
Open the result (unless --no-open). On macOS: open out/<id>.mp4.
Hand back. Three things to the user:
- the film id (so they can re-render via /docent-build <id>),
- the verdict score,
- one sentence naming the trade-off the film adjudicates.

Knowing when to stop and ask

Pause and ask the user instead when:

The repo is too large to cover at depth and no subsystem was named. Surface a candidate list of 2–4 subsystems with one-line summaries; let the user pick.
The survey surfaces two equally plausible angles (a control-plane vs. data-plane reading, a present vs. historical reading) — let the user pick the one the film should commit to.
review exhausts its round budget without passing the depth contract. Surface the failing dimensions; do not silently ship a film the judge rejected.

Failure modes

Repo not local — survey --mode ar clones the repo when given a URL. If the clone fails (auth, network), surface the failure and stop.
Agent CLI missing — survey and treatment shell out to claude or codex. If neither is on PATH, suggest /docent-doctor.
The judge keeps failing the trade-off dimension — the survey named components and flow but did not name what the system gives up by being what it is. Ask the user what the load-bearing trade-off is, or drop back to /docent-survey <repo> --mode ar and steer the analysis directly.