---
name: explain
description: This skill should be used when the user asks to explain technical, spec-heavy, workflow-heavy, code-change, artifact, diff, goal-progress, or multi-round agent work clearly. It should also be used when the user shows understanding friction such as asking for plain language, no jargon, what a spec looks like, what changed, whether work is done, what happened across many rounds, or asks for diagrams/UML/tables. Other skills may use this as Marcus's shared understanding interface.
---

# Explain

Turn technical or spec-heavy material into an understanding packet Marcus can read once and understand. Explain the structure, mechanism, concrete shape, and boundaries of the thing. Do not critique, audit, quiz, or review correctness unless Marcus explicitly asks for that instead.

## Audience Model

Explain as if speaking to a PM who has technical background but has not worked on this project and is not currently doing the engineering work. The output should let that person understand the spec's shape, moving parts, responsibilities, runtime behavior, status, important boundaries, and what is not included without reading code or prior session history.

This means:

- Do not teach basic CS concepts.
- Do not assume project-specific names are meaningful.
- Translate opaque project terms into responsibilities and mechanisms.
- Show the architecture and flow visually when the explanation concerns a system, spec, workflow, or multi-step change.
- Prefer product/spec comprehension over implementation detail unless the implementation detail changes the concept.

## Workflow

1. Identify the object being explained: thing, plan, spec, artifact, diff/change, workflow, architecture, or progress across rounds.
2. If the object already exists, read evidence first. Use current source files, specs, diffs, logs, goal state, workflow state, architecture docs, official docs, or result artifacts as applicable. Do not explain existing state from memory when evidence is available.
3. Choose the smallest packet a technically literate PM can understand in one pass. Compress large material into structure; do not dump raw detail.
4. Include the fixed spine for non-trivial explanations: `What this is`, `Why it matters`, `Concept model`, `Mechanism`, `Boundaries / not included`, and `What to notice`.
5. Define the thing before naming it. On first mention, explain what it is, why it exists, and how it relates to surrounding parts; only then use the project term or shorthand.
6. Draw the boundary explicitly. Identify the most likely misunderstandings, expected-but-not-delivered features, unchanged old behavior, unproven quality claims, or follow-up gates. Do not try to list every possible non-goal; pick the exclusions a reader could reasonably assume from the surrounding context.
7. Put diagrams where they teach the concept, not at the end. For system/spec explanations, include a UML-style concept/component diagram in `Concept model` when there are multiple named parts, and a sequence diagram in `Mechanism` when behavior crosses actors or layers.
8. Include one worked example for non-trivial explanations. Prefer the current task's real situation.
9. Keep the tone plain and precise. Default output language is zh-TW; keep standard CS/product/workflow terms, APIs, commands, file paths, and code identifiers in English.

## Output Order

Use this order unless a smaller answer is clearly enough:

1. One-line answer.
2. `Evidence checked`, when explaining existing artifact/progress/diff/spec/state.
3. `What this is`.
4. `Why it matters`.
5. `Concept model`.
6. `Mechanism`, with a sequence diagram when useful.
7. `Boundaries / not included`.
8. Status table, timeline, or other external representation when the explanation is about progress/completion.
9. `Worked example`.
10. `What to notice`.

## Evidence Rules

- Existing spec or draft: read the spec or draft.
- Existing diff or change: read `git diff`, touched files, and relevant docs when the change affects architecture/workflow.
- Existing progress or rounds: read goal state, plan, workflow logs, result artifacts, state files, or round summaries.
- Existing architecture or workflow: read the corresponding docs or runtime state.
- External technology: use official docs or primary source material.
- Include a short `Evidence checked` list. Do not add line-by-line citations unless Marcus asks for audit, blame, or correctness review.
- If evidence is incomplete, say exactly what the explanation is based on.
- For exclusions, separate what is confirmed not included from what is only not shown in the checked evidence. Use phrases like "I did not see evidence that..." when the evidence cannot prove a negative.

## External Representation Routing

Choose the representation that exposes the structure best. Prefer placing it inside the section it explains:

| Content type | Default representation |
|---|---|
| Concepts, names, boundaries | UML-style concept map or component diagram in `Concept model` |
| Flow, event, request path | Sequence diagram in `Mechanism` |
| State transition, lifecycle | State machine |
| Rules, permissions, routing, classification | Decision table |
| Data structure, relations | ER diagram or object model |
| User operation, agent interaction | Scenario walkthrough |
| UI, dashboard, artifact shape | Wireframe or annotated mock |
| Goal progress, rounds, completion state | Status table or timeline |
| Spec shape | Annotated outline or concept map |
| Boundaries, exclusions, likely misunderstandings | Boundary table: `Assumption` / `Reality` / `Why this matters` |

Do not force one diagram type for every case. Use multiple compact diagrams when the material has both an architecture shape and a runtime flow.

## Tone Rules

- Assume Marcus understands standard CS, product, and workflow concepts. Do not over-explain ordinary terms such as `state machine`, `interface`, `adapter`, `invariant`, or `DTO`.
- Do not invent acronyms, cute metaphors, dramatic verbs, vague nouns, or private jargon.
- Do not use a pronoun, label, or project term as a substitute for saying what something is. Avoid first mentions like "this layer", "the lane", "the shadow", "Genesis", or "the engine" unless the sentence defines the object in plain responsibility terms.
- Explain by logic and context: what problem existed, what part was added or changed, what it reads, what it writes, what it affects, and what it does not affect.
- When explaining a boundary, say what the thing is not, what it does not change, what it does not prove yet, or what readers may incorrectly expect it to include.
- Treat project terms as suspect when they were coined by prior agents or are not self-explanatory, even if they appear in docs. Do not lead with opaque compound names such as `Profile Fallback Engine`, `Director admission shadow`, or `private evidence` unless you define them by responsibility first.
- Prefer a plain responsibility label plus the original term in parentheses, for example: "舊的新遊戲產生路徑（docs call this the legacy profile/fallback path）".
- Use established project terms only when they point to concrete roles or mechanisms, and define them the first time if the words alone do not reveal what the part does.
- Prefer ordinary precise verbs: read, write, check, route, block, fallback, require approval, update state, produce output.
- If a new term is truly needed, define it by responsibility in plain language.
- Do not overclaim exclusions. If the checked evidence does not confirm whether something exists, name it as an evidence boundary instead of presenting it as fact.
- Keep explanation neutral. Do not add `Recommendation`, `Critique`, or `Review focus` unless Marcus asks for review/critique.

## Non-Goals

`/explain` does not:

- critique the artifact
- review correctness
- challenge the plan
- produce a quiz
- replace code review
- replace audit or blame investigation
- dump raw details

If Marcus asks for review, critique, audit, blame, or implementation, use the appropriate mode or skill instead.

## Calibration Examples

Read `examples/progress-change-comprehension.md` when you need a model for explaining a long technical session, phase progress, or what changed across many rounds.