briefBLOCK

Interactive docs for coding agents. Agents publish research as readable sessions; humans read, annotate, and decide, then send answers back as one prompt.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: brief
description: Use when research, analysis, review, or planning work produces findings too large or too visual for chat, such as an architecture walkthrough, an incident review, a migration plan, or a comparison of options. Publishes the work as an interactive document on Brief (https://brief.algoryth.me) that the human reads, annotates, questions, and answers any open decisions in, then replies back into the conversation.
---

# Publish a document to Brief

## Overview

Brief turns a piece of agent work into a web document the human can act on. You POST one JSON payload; the API returns a URL; the human opens it, reads the sections, highlights passages to ask about or change, answers any decision cards, and pastes a generated reply back into this conversation. You then act on that reply.

The payload has exactly three top-level keys: `meta`, `sections`, and `decisions`. Everything the reader sees is built from those.

## When to use

Use it when the work produced more than chat carries well: evidence the reader should see laid out, a flow or structure that prose flattens, numbers worth a chart, or a choice that needs the evidence in front of the reader. A document does not need a decision to be worth publishing. The reader can question or ask for an edit on any passage, so an explanation or a review still gets a reply back.

Do not use it for an answer that fits in a few chat paragraphs, or as a place to dump raw logs and command output.

## Who reads it

The reader asked for this document because they did not follow the work. They know their product and what they asked you to do. They do not know the files you opened, the commands you ran, the names you gave things along the way, the ticket and task numbers you tracked, or what an earlier document said. Write every sentence so that person can follow it without asking. If they would have to ask "what is that?", the sentence is not finished.

A document fails this reader in two ways. It buries the point under the story of how you worked, or it reads smoothly and leaves out the facts the reader came for. "What the reader needs" and "Writing for the reader" below guard against each.

## Workflow

1. **Research and verify.** Read the real files, trace the real code paths, run the real commands. Every number and claim that reaches the payload must come from something you actually saw. Note where each fact came from; that note belongs in an evidence block, not in your sentences.
2. **List what the reader needs.** Find the kind of work in "What the reader needs" below and write down each fact its row asks for. A fact you could not get is a gap to state in the document, not a row to drop.
3. **Plan the sections.** Section 1 is a summary of two to four sentences: what you found or did, what it means for the reader, and what they should do now, with no name the reader has not met. Do not restate the request. After it comes one topic per section, in reading order, numbered from 1.
4. **Pick a block for each fact.** Use "Choosing blocks" below to match each fact to the block built for its shape, then read `BLOCKS.md` in this skill directory for that block's exact fields, enum values, and a valid JSON example. It covers all 22 block types.
5. **Write for the reader.** Follow "Writing for the reader" below.
6. **Add decisions only for calls the human must make.** Settle every question you can answer by thinking it through or checking, and say in the document what you chose. A decision is for a choice that turns on the human's priorities, money, risk, or taste, with at least two options you would accept. Write those last, so the options reflect what the research found, each with honest `detail` text and usually a `why` that states your recommendation and its cost. When nothing is left to decide, send `"decisions": []`; the reader then shows no decision area.
7. **Reread it as the reader.** Before validating, read the payload as someone who saw none of this session. Every name, path, id, abbreviation, and number is explained where it first appears, or it goes. Every fact from step 2 is there. No sentence describes how you worked.
8. **Validate before publishing.** Write the payload to a file and run `node <skill-dir>/validate.mjs payload.json`. It is offline, needs no install, and it rejects exactly what the API rejects. It also prints readability hints. Do not skip it; a failed POST costs a request against a ten-per-minute limit and returns at most ten of the problems.
9. **Publish and hand over the URL.** Give the human the link and nothing else; the document carries the content now.
10. **Act on the reply.** The human pastes a generated prompt back into the conversation. See "What comes back" below.

This skill directory holds three things you will use: `BLOCKS.md` (every field of every block), `example.payload.json` (a complete, valid document to model yours on), and `validate.mjs` (the pre-flight check).

## What the reader needs

A document can read well and still fail because the number the reader came for is missing. Before writing, find the row for the kind of work and collect each fact it lists.

| Kind of work | Facts the reader needs | Blocks that carry them |
| --- | --- | --- |
| Performance, load, or capacity | The target, and the machine or plan it runs on with its size and price. The result against the target, before and after, measured the same way. How each number was measured: tool, load, data size, runs, and spread. Where the time or the resources go. Each fix, shown as code. How cost grows with users or data. The money cost now and at the target. What was not measured. | `stat`, `table`, `histogram`, `scatter`, `bigo`, `ba`, `coverage` |
| Bug, incident, or failed test | What the user saw. The cause, as a chain of steps. The fix. The proof that it works. What can still go wrong. | `seq`, `state`, or a `mermaid` flowchart, then `ba`, `good`, `warn` |
| Code review | What the change is for, in the user's terms. The ver

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (3)

curl -sS -X POST https://brief-api.algoryth.me/api/session \

example.payload.json

payload.schema.json

Gates applied: critical_finding, no_behavioural_pass, undeclared_transfer.