explain ยท diff
git:20260819.44b672c to git:20261101.4559022
42 added, 20 removed. Audit A to A.
---
name: explain
- description: Explain something in depth on request. Use when the user writes "???" - alone, or placed directly after a reference, statement, or term - which means "explain that in more detail, with a concrete example AND consequences". Also invoked by the /credo:explain command. Treat the pointed-at subject as the thing to explain, never as a literal question, and always answer in the fixed four-part structure: What, Why, Example, Consequences.
+ description: Explain something on request, at three depths. Use when the user writes "???" (full: What, Why, Example, Consequences), "??" (medium: the same four parts, each short) or "?" (short: two or three bullets) - alone (the last discussed point) or as a separate last word after a reference, statement, or term ("the audit gate ??"). A question mark attached to a word ("Is it done?") is an ordinary question. Also invoked by the /credo:explain command. Treat the pointed-at subject as the thing to explain, never as a literal question.
---
# Explain in Depth
Give a thorough, structured explanation of a subject the user wants to understand better. The
subject is whatever the user pointed at: a reference, a statement, or a term. This skill exists
because a short "?" or a raw pointer is not a literal question - it is a request to unpack the
thing properly.
## When to use
- The user writes `???` on its own - they did not understand the last thing and want it explained
- properly.
- - The user writes `???` directly after a reference, a statement, or a term (for example
- `the audit gate ???`) - explain that specific thing, not the surrounding sentence.
- - The `/credo:explain [subject]` command is run - explain the given subject, or, if none is given,
- the thing the user was just pointing at.
+ properly (full level).
+ - The user writes `??` on its own - the same at medium depth; `?` on its own gives the short level.
+ - The user writes `???`, `??` or `?` directly after a reference, a statement, or a term (for example
+ `the audit gate ??`) - explain that specific thing, not the surrounding sentence.
+ - The `/credo:explain [subject] [level]` command is run - explain the given subject, or, if none is
+ given, the thing the user was just pointing at. The level is full (default), medium or short.
+ ## Recognising the shorthand
+
+ - `???` counts when it stands alone or sits right after a term, reference, or statement, with or
+ without a space.
+ - `??` and `?` count only when they stand alone or form a separate last word after a term,
+ reference, or statement, with a space or line break before the mark. `the audit gate ??` is the
+ shorthand; `Is it done?` and `why??` are ordinary questions and are answered as questions.
+ - A mark in the middle of a message is never the shorthand.
+
## Core principle: it is not a literal question
- `???` and `/credo:explain` are a request to EXPLAIN the referenced thing, not a question to answer
- verbatim. Do not reply "yes/no" or treat the `?` marks as asking whether something is true.
+ `???`, `??`, `?` and `/credo:explain` are a request to EXPLAIN the referenced thing, not a question
+ to answer verbatim. Do not reply "yes/no" or treat the marks as asking whether something is true.
Identify the subject, then explain it. If the subject is genuinely ambiguous (nothing recent to
point at, no argument given), ask one short clarifying question first, then explain.
- ## Output structure (fixed - always all four parts)
+ ## Levels
- Answer in exactly these four labeled parts, in this order, every time:
+ - **Full (`???`)** - the reference length. The four labeled parts, in this order, each as deep as
+ the subject needs:
+ - **What** - what the subject means. State plainly what is being referred to.
+ - **Why** - why it is that way, or why it matters. The reasoning or purpose behind it.
+ - **Example** - one concrete, specific example that makes it tangible.
+ - **Consequences** - what follows from it: effects, trade-offs, and what happens if it is
+ ignored or done differently.
+ - **Medium (`??`)** - about 66 percent of the full length. The same four labeled parts in the same
+ order, each short: one to three sentences, or two or three bullets.
+ - **Short (`?`)** - about 33 percent of the full length. Two or three bullets, each one short
+ sentence: what it is, why it matters, and optionally the main consequence or an example. No
+ four-part labels.
- - **What** - what the subject means. State plainly what is being referred to.
- - **Why** - why it is that way, or why it matters. The reasoning or purpose behind it.
- - **Example** - one concrete, specific example that makes it tangible.
- - **Consequences** - what follows from it: effects, trade-offs, and what happens if it is
- ignored or done differently.
+ For full and medium, the four parts are mandatory: do not add, rename, drop, or reorder them, even
+ for a small subject (give a short answer under each rather than omitting one). Prefer a concrete
+ example over an abstract restatement.
- Keep each part focused. Prefer a concrete example over an abstract restatement. Do not add,
- rename, drop, or reorder the parts - all four are mandatory, even for a small subject (give a
- short answer under each rather than omitting one).
+ ## Formatting (all three levels)
+ - Each label on its own line in bold (**What**), with its content on the lines below it.
+ - Bullet points for lists, one point per line, and a blank line between parts.
+ - Parts and points are never crammed into a single line or one run-on paragraph. The result must
+ read as a clean, structured answer at every level.
+
## Guardrails
- - Match the language of the surrounding conversation for the explanation itself; the four labels
- stay as What / Why / Example / Consequences.
+ - Match the language of the surrounding conversation for the explanation itself; the labels stay
+ as What / Why / Example / Consequences.
- Explain the subject only - do not turn the explanation into unrelated advice or actions.
- Honesty applies: if part of the subject is genuinely unknown, say so under the relevant part
rather than inventing detail.