explain

Files (1)

• SKILL.md

SKILL.md (first lines)

> 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 resolution order:

> **path → artifact mode · exact / normalized lexicon key → term mode ·
> otherwise → passage mode.**

1. **A resolvable path to a spec or ADR** → artifact mode. Examples:
   `/jig:explain docs/specs/062-refactor-workflow/spec.md`,
   `/jig:explain docs/decisions/adr-0021-lexicon-home-and-overlay.md`. A spec
   *directory* (`docs/specs/065-lower-vocabulary-barrier/`) resolves to its
   `spec.md`.
2. **A word or short phrase that is an exact / normalized lexicon key** → term
   mode. Examples: `/jig:explain SPIDR`, `/jig:explain "vertical slice"`,
   `/jig:explain deviation log`. Matching is case-insensitive and
   whitespace-collapsed (the lexicon's key convention).
3. **Anything else** → passage mode (a pasted snippet of jig output, or any
   text that is neither a resolvable path nor a lexicon key).

Two carve-outs sit on top of that order:

- **Term-mode honesty (do not let passage mode swallow the absent-term
  signal).** An unknown **short query phrase** — a brief, single-line argument
  that *looks* like it wants a definition but isn't a lexicon key — still routes
  to **term mode** and gets its honest *"that term isn't in the lexicon"* flag
  (see Term mode step 4). It is **not** silently absorbed into a passage-mode
  guess. Distinguish by **shape, not word count**: a short single-line phrase is
  a term query (some lexicon keys are themselves 3+ words, e.g. `closed-spec
  drift policy`); a multi-line block or output-shaped paste is a passage. Passage
  mode is for pasted output, not a greedy catch-all that erodes the absent-term
  signal.
- **Path-shaped-but-unresolvable input — ask, don't guess (clarify Q1).** When
  the argument **looks like a repo file path** — it sits under `docs/` (e.g.
  `docs/specs/…`, `docs/decisions/…`) or ends in a doc/code extension like `.md`
  — but **no file exists there**, the most likely cause is a typo, a stale path,
  or a path from another repo. **Ask the user whether they meant a file path (and

From ramboz/jig, MIT.

More from ramboz/jig