Explainer

Skill: pageship-explainer

An explainer shows the reader how something works: the parts, what passes between them, and the rules that decide what happens next. Figures carry the explanation and short prose sits around them. A reader who looks only at the figures and their captions still learns how it works.

Your agent picks an explainer when you ask how something works, such as how a retry policy decides what to retry, or how a ticket moves through queues.

What the reader gets

The parts come in this order:

1. Title and answer. What the explainer covers, then the answer to your question in one or two sentences.
2. Overview. A figure of the whole mechanism, after the sentences that introduce its parts.
3. One section per stage or rule, in the order the mechanism runs. Each has one figure and at most two short paragraphs.
4. Exceptions and limits, when the source gives any.
5. Open questions.
6. Sources. Each file, with line numbers for code, and each document the explainer draws on.

What the skill works from

When the source is code or configuration, what its lines do is the source. The agent reads the files your request points to, and any file they call that it needs.

It then traces the mechanism: each part, what moves between parts, each rule with its numbers and where it lives, and every way the process ends. It traces only what the answer needs. Logging, metrics or a neighbouring feature in the same files stay out.

Code it can’t read stays a gap. The explainer says what the calling code shows about it and nothing about what it does inside. The explainer describes a setting no code uses as declared, not as doing something.

Each figure makes one claim, written as its caption. Every arrow carries a label from the source, such as “status 429” or “customer replies”. An arrow the source gives no label for becomes an open question.

The agent introduces each term before it is used, so a new reader can follow from the top.

Before it hands over the file, the agent asks a fresh subagent, when it can start one, to read the file beside the source and quote every sentence that claims more than the source states. When a subagent writes the explainer and can’t start another, your agent starts that reader itself, and the writer fixes what it quotes.

Patterns it often uses

• Diagrams for the overview and most sections.
• Code blocks for the line a rule lives in, at most one per section.
• Interaction for stepping through stages or tracing a path.

Example request

Explain how webhook retries work in this repo, for someone new to the team.
Start from src/webhooks/deliver.ts.