--- name: rite-explain description: User-invoked explainer that teaches one concept, diff, idea, or recent-work recap with an optional retrieval check-in. argument-hint: "[a concept | a diff ref | an idea | \"what did I do this week?\"] — or bare to be asked" user-invocable: true disable-model-invocation: true --- # /rite-explain — the human half of the learning loop Agent-driven development removed the learning that writing code by hand used to give the developer. When the agent writes the code, the human stops absorbing the codebase. `/rite-explain` is the replacement: it teaches the developer **one** thing well — a concept, a change, an idea, or a window of their own recent work — so they keep learning while the agents do the writing. For a specific change, it can instead write a **walkthrough**: a human review guide organized by concern, risk stops, and manual observations. This is the **complement of [`/rite-learn`](../rite-learn/SKILL.md)**, and the two together are the whole compounding story. `/rite-learn` teaches the **repo** — it promotes recurring lessons into rules and principles the next feature reads. `/rite-explain` teaches the **person** — the mental model the next feature needs a human to actually hold. A team that only runs `/rite-learn` compounds a codebase whose own maintainers understand it less each week. Run both. Read-only against source. It reads artifacts and code; it writes exactly one explainer file to `.devrites/explainers/` and never edits source, specs, or rules. ## Who the explainer is for The developer, personally. Dense, technical, one voice — no audience adaptation, no "for beginners" softening, no executive summary. It is a display artifact: no embedded quizzes or widgets — the check-in (below) happens live in the session, where an answer can actually be graded. If the user asked for prep for a meeting or a teammate, it preps **them** to explain the thing; it does not produce the deck. ## Model tiers Dispatch by task shape, per [`devrites-lib/reference/model-tiers.md`](../devrites-lib/reference/model-tiers.md): - **extraction tier** — the work-recap scout and any repo-profiling: search-and-quote, run under a read budget, write findings to the run's scratch dossier, return only a gist. - **ceiling tier** — the explainer composition and the check-in reasoning. These run inline in the orchestrator's own model; nothing is dispatched down. Teaching quality is the whole product — do not cheapen it. The degradation rule in that file applies: no per-agent model control → run the scout inline under the same budget. ## Workflow ### 1. Classify the input — load the intake reference The four input shapes (concept · diff · idea · work-recap) each ground and compose differently, and each drives a different check-in. Diff inputs also branch into explainer vs walkthrough composition. Getting the shape wrong wastes the whole artifact. **Load [`reference/intake.md`](reference/intake.md) now** — it owns the classification rules, the `diff:` / `since:` / `output:` token table, the concept-vs-diff tiebreak, and the check-in mechanics per shape. Do not improvise classification from this file; the detail lives there so this one stays legible, and skipping it means guessing the shape. **Bare invocation** (no input): ask **one** blocking question (`AskUserQuestion` when the harness has it, else the harness's blocking-question tool — `request_user_input` on Codex) — "What should I explain?" — offering "a recap of my recent work in this repo" as a shortcut option alongside free text. Never emit a default explainer unprompted. ### 2. Ground Match grounding to the shape (full rules in the intake reference). DevRites gives you grounding for free — prefer it over re-deriving: - A **diff** or **recap** → the workspace and archive: `seal.md`, `evidence.md`, `decisions.md`, `traceability.md`, the shipped `.devrites/archive//`, and `git log` / `git diff`. - A **concept** with footprint in this repo → the live code (codegraph / graphify first), plus any `.devrites/principles.md` or ADRs that already take a position on it. - An **idea** or a concept with no repo footprint → the user's framing plus, only if it sharpens the teaching, current external sources (weight by date; the year is 2026). Create the run directory before composing so scout dossiers have a home: ```bash RUN_DIR=".devrites/explainers/$(date +%Y%m%d)-"; mkdir -p "$RUN_DIR" ``` ### 3. Compose the explainer For diff inputs that ask for `walkthrough:`, "checkpoint", "walk me through", or human review, write `$RUN_DIR/walkthrough.md` using the walkthrough composition in `reference/intake.md`, then skip the active-recall check-in unless the user asks for teaching too. Otherwise write one dense artifact at `$RUN_DIR/explainer.md`. It must **teach**, not summarize: 1. **One thing.** A single clear takeaway named in the first two lines. If the input sprawls, teach the highest-leverage slice and say what you cut. **Completion:** the first two lines state one takeaway and any deferred topics. 2. **Build the model, don't list facts.** Start from what the developer already knows in *this* codebase and move to the new thing. Concrete before abstract — a real symbol, file, or line from the grounding beats a generic example every time. **Completion:** the explanation connects a known project anchor to the new model without a fact dump. 3. **Show the load-bearing detail.** Quote the actual diff hunk, the real function, the specific config — with `file:line` pointers so the developer can go read it. 4. **Visual where it earns it.** A small diagram, a before/after, or a worked trace when the shape is spatial or sequential. Not decoration — only when it carries the idea faster than prose. **Completion:** the visual carries a named relationship faster than prose, or this branch is explicitly skipped. 5. **Human voice.** Follow [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md): no throat-clearing, no false-binary contrast, no marketing adjectives. One senior engineer explaining to another. ### 4. Offer the check-in (optional, active recall) Retention comes from *retrieving*, not re-reading. After the explainer, offer one check-in via the harness's blocking-question tool (`AskUserQuestion`, or `request_user_input` on Codex) — the user answers **first**, then you confirm or correct. The shape sets the form (mechanics in the intake reference): - **diff / recap** → **predict-then-reveal**: ask what a specific hunk changes or why a decision was made *before* showing the reveal. - **concept / idea** → a **checked exercise**: one small problem the developer solves, then you grade it against the model you just taught. Skippable when the material does not warrant retention work (a one-off, or the user declines). Do not force it; offer once. ## Gotchas - **Teach one thing.** An explainer that covers five things teaches none. Cut ruthlessly; queue the rest as "next time". - **Ground it or don't claim it.** A concept explainer with no `file:line` or real example is a Wikipedia paragraph. If it has footprint in this repo, quote the repo. - **Not a review.** `/rite-explain` never judges the code or files findings — that is `/rite-review`. It explains what *is*, adversarially neutral. - **Not `/rite-learn`.** It writes to `.devrites/explainers/`, never to `learnings.md`, `principles.md`, or any rule file. Teaching the human is not promoting a repo rule. ## Output Reply-contract exception: cross-feature learning utility; may run with no active feature, so it skips `devrites-engine progress` when no workspace exists. Otherwise follows [`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md). ``` Done: explained as a explainer OR walked through for human review. Changed: .devrites/explainers/-/ Evidence: grounded in ; check-in ; walkthrough stops Open: Next: Record: .devrites/explainers/-/explainer.md ↻ Hygiene: /clear after reading; the explainer is on disk ```