# Docent Ar > | - **Type:** Skill - **Install:** `agentstack add skill-benelser-docent-docent-ar` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [benelser](https://agentstack.voostack.com/s/benelser) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [benelser](https://github.com/benelser) - **Source:** https://github.com/benelser/docent/tree/main/packages/agent/skills/docent-ar - **Website:** https://github.com/benelser/docent ## Install ```sh agentstack add skill-benelser-docent-docent-ar ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 [--subsystem X] [--id X] [--scale S] [--no-open]` - `` — 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: ``). - `--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 `bun`, `ffmpeg`, and the agent CLI are on PATH. If anything obvious is missing, suggest `/docent-doctor` and stop. 2. **Survey** — architecture mode: ```bash bun packages/agent/scripts/survey.ts --mode ar [--subsystem X] [--id X] ``` The survey lands at `analysis/.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. 3. **Commit to a style.** Before the treatment, decide the visual register the film renders in: ```bash bun run docent style recommend ``` 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. ```bash bun run docent scene-fit recommend ``` 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. 4. **Treatment.** ```bash bun packages/agent/scripts/treatment.ts ``` Writes `treatments/.md`. Print the *Angle* line so the user sees the through-line you committed to. 5. **Spec — and interrogate it.** ```bash bun packages/agent/scripts/treatment.ts --to-spec bun packages/agent/scripts/flywheel.ts --max-rounds 2 ``` The first compiles the treatment into `films/.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/.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. 6. **Render.** ```bash bun run docent build --scale 1 ``` 7. **Open the result** (unless `--no-open`). On macOS: `open out/.mp4`. 8. **Hand back.** Three things to the user: - the film id (so they can re-render via `/docent-build `), - 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 --mode ar` and steer the analysis directly. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [benelser](https://github.com/benelser) - **Source:** [benelser/docent](https://github.com/benelser/docent) - **License:** MIT - **Homepage:** https://github.com/benelser/docent Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-benelser-docent-docent-ar - Seller: https://agentstack.voostack.com/s/benelser - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.