Explanation Template

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/templates/explanation.md
Description	Not specified

Source Content

Explanation Template

Understanding-oriented. Discusses the why and the tradeoffs, not the steps. Diátaxis mode: explanation.

Skeleton

# Why {{the design or approach}}

{{Two-person story first — it frames the stakes before anything else is
said: "Jack shipped the naive version and paged himself every weekend.
Jill added the queue and slept." The rest of the doc explains what Jill
understood.}}

{{The question this answers and why it matters now.}}

## The forces at play

{{Constraints, requirements, and tensions that shaped the design.}}

## How it works

{{The mental model — enough to reason about the system, not a reference dump.}}

{{Mermaid diagram of the architecture or flow — follow the diagram rules in ../mermaid.md.}}
_{{What to notice in the diagram.}}_

## Tradeoffs we accepted

{{What this buys, what it costs, and the alternatives not taken.}}

## The useful ending

{{One or two sentences, after everything above: what each person from the
opening walked away with, now that this is written down.}}

Rules for this template

• Open with the story, then the question it raises — the reader needs to feel the problem before any answer.
• Every abstract claim gets a concrete scene where the claim is visible.
• Alternatives not taken each get a #### heading, never bold names in one paragraph.
• If this records a binding decision, it belongs in the adr skill’s format instead.
• Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
• Reminders: story, own line per person · useful ending.
• Format: short paragraphs · lists and tables · diagram + “what to notice”.