/explain

name: explain
description: >
  Explain jig vocabulary and artifacts in plain language. Three modes: term
  mode defines one lexicon term; artifact mode walks through a spec or ADR and
  its linked references; passage mode explains pasted jig output. Output is
  ephemeral (chat-only). Auto-triggers when you say explain this term, walk me
  through this spec, explain this ADR, what does this output mean, or explain
  this snippet; invoke explicitly with `/jig:explain`. Defers to any other
  installed skill whose description identifies it as handling plain-language
  explanation, onboarding, or artifact walkthroughs. Does not defer to the
  generic built-in. Do not use for finished-slice compliance (use
  `/jig:independent-review` instead), cross-artifact analysis (use
  `/jig:analyze` instead), or glossary updates (use `/jig:memory-sync`
  instead).
user-invocable: true

> Spec 065 introduces this skill as jig's **on-demand explainer** — the third > consumer of the shipped lexicon (065-01). The barrier jig is lowering is > vocabulary: the artifacts are dense with opinionated jargon (SPIDR, ADR, > vertical slice, reconciliation, deviation log, DoR/AC/DoD, frontmatter) and > almost none of it is explained where the reader meets it. The hook (065-02) > surfaces one-line defs just-in-time; this skill is the **strong-handholding** > escalation — define a term in depth, or translate a whole dense spec/ADR into > plain language for a junior. > > Like `/jig:clarify`, `/jig:pr-review`, and `/jig:arch-review`, explain is a > **judgment skill** — it ships **no `.py` helper**. The only determinism it > needs (load the merged lexicon, read the named artifact, resolve the refs it > links) Claude runs inline via Read + the 065-01 loader. The plain-language > *quality* is judgment exercised by this prompt, not something a unit test can > assert — the same accepted shape as every judgment-only jig skill.

What this skill does

Translates jig's vocabulary and artifacts into plain language for a reader who is **new here** — a junior, or anyone meeting spec-driven work for the first time. It has three modes, selected by what the argument is:

• **Term mode** — the argument is a word or short phrase (`/jig:explain

reconciliation`). The skill returns that term's plain-language definition from the **merged lexicon** (jig's shipped `lexicon.json` with the project's `docs/memory/glossary.md` overlaid on top — 065-01), plus its example and see-also when present. If the term is **not** in the lexicon, the skill says so plainly rather than inventing a definition.

• **Artifact mode** — the argument is a path to a spec or ADR

(`/jig:explain docs/specs/062-refactor-workflow/spec.md`). The skill produces a fixed-shape, junior-grade **walkthrough** of that artifact, defining every jig term it uses inline and **auto-pulling the ADRs/specs it links** so the reader doesn't have to chase references.

• **Passage mode** — the argument is a **pasted snippet of jig output** that is

neither a single term nor a file path: a review `VERDICT:` envelope, a status-board row like `IN_PROGRESS (wt-me)`, a hook's *"Unrecognized references in prompt…"* message, a `workflow.py` transition refusal, a `session-plan` block. The skill scans the snippet for jig terms (defining each inline) and explains **what it is** and **what — if anything — the reader should do**. When the snippet carries **no jig vocabulary at all**, it gives a plain generic read. This is the mode for the most common confusion moment: a reader pastes the thing that stumped them.

All three modes are **ephemeral**: the output is chat-only. The skill writes nothing to disk — no `--save` flag, no appended section, no file mutation. This keeps the hot path clean (the 055/057 context-cost discipline) and matches the clarify-Q3 resolution that explain output is always chat-only.

This is a **best-effort comprehension floor**, not a guarantee the reader will understand everything — the same honest framing as jig's security floor (ADR-0013) and the soft context mechanisms (055/057). The skill surfaces and explains; it does not certify understanding.

When to use vs. when to defer

**Defer to a richer installed skill first.** If another installed skill's description identifies it as handling plain-language explanation, onboarding, or artifact/codebase walkthroughs, prefer it — jig's explain is a slim baseline. This skill does **not** defer to the generic built-in (a bare `explain`/`init` with no onboarding framing); it only steps aside for a skill whose description names the explanation/onboarding/walkthrough job.

Three sibling jig skills are easy to confuse with this one:

• **`/jig:independent-review`** — reviews a *finished implementation* against

its spec's ACs. It evaluates whether the code is correct; this skill explains what the spec *says* to a reader who finds it dense. Reach for independent-review after a slice is implemented; reach for explain when a reader is stuck on the vocabulary or shape of an artifact.

• **`/jig:analyze`** — cross-artifact consistency analysis: does spec A

contradict ADR B? It hunts for *drift between* artifacts. This skill explains *one* artifact (and the refs it pulls in) to a human. Reach for analyze to audit alignment; reach for explain to understand.

• **`/jig:memory-sync`** — *persists* a new term to the project glossary or

hot cache. It writes vocabulary. This skill *reads* the existing lexicon to explain a term; it never authors one. Reach for memory-sync to record a term; reach for explain to look one up. (If explain flags a term as absent and the user wants it captured, route them to `/jig:memory-sync`.)

Rule of thumb: **understand an artifact or term → this skill. Persist a term → `/jig:memory-sync`. Check the implementation → `/jig:independent-review`. Audit across artifacts → `/jig:analyze`.**

Inputs — mode precedence

The argument selects the mode by a fixed res