---
name: help
description: "Use whenever the person needs to understand what is going on in this collection: they ask (how something works, what a term or a verb's answer means, what is happening in a run, what can be done here, how to start), they call help, or, unasked, the moment you notice they do not know or do not understand something of this ecosystem (a term they misuse or ask about, surprise at what a run or a skill does, a choice they cannot make for lack of the picture). Explains, in simple terms, what you are doing together and how this part of the landscape works, from the current work and its content, then guides them on. Not for running the skill it explains, and not for offering a skill unasked (next-step)."
---

# Help

**Explain what you are doing together and how it works, from where the person is, never from a
manual.** Their question, or what they did not follow, and what is going on now (the skill in use,
the run on the board, the document open, the last answer a verb printed) say which part of the
landscape to explain: what is happening, why, how the pieces fit, what can be done next. Explain
that, in their terms and with this work's own content, then guide them on.

**Unasked, explain as you go**: when the person misuses a term, is surprised by what a run or a
skill did, or cannot choose for lack of the picture, give the few lines they miss at that point,
without stopping the work, then carry on.

## Simple terms, always

**Write for a tired engineer: someone smart who has no energy left for decoding.** This rule has
no exception.

- **Short sentences, plain words.** One idea per sentence.
- **No jargon left unexplained.** A term of this collection (seat, phase, task, protocol, verifier,
  board, data home) gets a plain meaning the first time, then is used the same way.
- **Concrete before abstract**: what is happening in their work first, the general rule after,
  if at all.
- **The answer first**, then only what they need to act on it. Nothing they did not ask about.

## Read the context first

- **What is running**: the skill loaded in this session; a run on the board (`swarm status`, its
  phase, its members, what waits on the person); the document being worked on (`aiview status`).
- **What they just met**: a verb's answer, a phase message, a findings table, a board event, a
  document's kind, a term (seat, phase, task, protocol, verifier, the data home).

## Explain

- **The part they asked about, as it applies here**: what it is, why it is there, what happens
  next and what is theirs to decide. A run's state: where it stands, who waits on whom, what
  unblocks it. A term: one sentence, then what it means in this run or this project.
- **Where to see it**: the aiview link (the documents, `/board`), the document by name, the board
  post by its number.
- **Short**: a few lines, a list when there are steps; a diagram (the `write-diagrams` skill) only
  when the question is about how pieces connect.
- **Then hand back**: the work continues where it was. A skill the explanation points to is
  offered as the `next-step` skill offers, never run unasked.

## When the question is broad

"What can it do", "how do I start": one screen, each line a kind of help with an example drawn
from **this project's own work** (its open documents, its recent commits, the subject of the
conversation):

- **Think it through**: the `interview` skill, the `brainstorm` skill (a board that keeps the
  decisions).
- **Decide with several voices**: the `brainswarm` skill (debate, brainstorm, editorial seats).
- **Plan and build**: the `write-plan` and `execute-plan` skills; a `swarm` of workers, with
  build-verify when the result must be walked.
- **Design a screen**: the `design-prototype` skill. **Review**: the `pr-review` skill. **Keep
  conventions**: the `write-conventions` skill.
- **Watch it all**: aiview, the documents and the board.

End on the one you would start with here, and why, offered as the `next-step` skill offers.