readout

Readout

A readout turns an investigation into a durable HTML document someone can read weeks later without any of the original context. It starts one of two ways:

• Snapshot mode — invoked mid-conversation ("write this up"): the conversation's accumulated findings are the source material.
• Research mode — invoked fresh ("/readout on how github webhook events are processed in the server"): there is no conversation to mine, so the investigation itself is part of the job.

Either way, invoking this skill is a side task. Your job as the main agent is to sharpen the scope, launch a child agent with a good brief, and get out of the way — the child does the mining/research and the writing, keeping that (often large) work out of your context window.

Orchestrator workflow

1. Sharpen the scope — ask before launching

A vague brief produces a vague document. Before launching you should be able to list the specific questions the document will answer; if you can't, interview the user first:

• Ask 2–4 targeted questions, offering concrete options rather than open prompts — take a quick look at the code or topic first so the options are real (subsystems, entry points, competing concerns). For "/readout on how github webhook events are processed": which direction matters — inbound triggers, post-back, or both? a current-state reference or a gotcha hunt? which repo(s)?
• Always pin down depth and audience: high-level orientation vs. deep mechanics with line-level grounding; personal notes vs. shared with the team.
• Respect a shrug. "Just a high-level overview" is a valid answer — record it in the brief and move on rather than interrogating. Even then, try to extract the two or three questions the reader most needs answered; specificity is what makes a readout useful.
• Skip the interview when the scope is already specific — a snapshot of a focused conversation, or a precise research request, needs no questions. In snapshot mode the conversation usually supplies the questions; ask only when the invocation is ambiguous about which threads to include.

2. Compose the brief

Write a short brief (roughly 10–20 lines) carrying pointers, not payloads:

• A working title / topic, and the mode (snapshot or research)
• The specific questions the document must answer (from the conversation or the interview), plus depth and audience
• Scope: which threads/subsystems to cover, and anything to explicitly exclude
• Snapshot mode: headline conclusions worth centering the doc on, one line each — the child pulls the full content from conversation history itself, so don't paste findings wholesale
• Research mode: starting pointers — entry-point files, symbols, or directories you already know about
• Absolute paths to the repos/directories that ground the work
• Each repo's hosted URL and the examined commit when known (e.g. github.com/org/repo @ abc123), so the document can hyperlink code references

3. Launch one local child agent

Spawn exactly one child agent via run_agents, local execution. Local matters: the document lands on the user's filesystem and opens in their browser. Name the child readout-<topic-slug>.

Build the child's prompt from the template below. It must include:

• The brief
• The source-material block matching the mode (snapshot mode also needs your agent run ID — current_run_id from the orchestration runtime context — so the child can mine the parent conversation with search_conversation_history)
• The instruction to read references/doc-guide.md from this skill's directory before writing
• The output path convention and completion protocol

4. Get back to work

After launching, resume whatever you were doing, or end your turn — the child's completion message arrives on its own; relay the file path to the user with a one-line description when it does. In research mode a fresh conversation may have nothing else pending; just end the turn. Don't sit in a wait loop unless the user asked to wait for the document.

Child agent prompt template

Adapt this; keep the structure, and include the source-material block that matches the mode.

Fallbacks

• Child spawning unavailable or denied: produce the document yourself, following references/doc-guide.md. If a research subagent is available, delegate the conversation-mining or code investigation to it so your context still stays lean.
• Child can't search conversation history (snapshot mode; it will report this back): reply to the child with a distilled dump of the findings so it can proceed — this is the one case where payload-in-prompt is the right call.
• User-provided material instead of a conversation (transcripts, files, links): treat that material as the source; everything else in the workflow is unchanged.