Write a good brief
A headline gets you a piece; an outline gets you the piece you meant. What to put in a brief, and how to ask for a shape.
The kernel writes from the brief and nothing else. Everything you want in the piece has to be in the brief, or in the research outline that becomes the brief.
What a brief can be
- A headline. "Why remote work is here to stay." The kernel develops the argument itself. Fine for opinion, weak for anything factual.
- A topic plus notes. A headline and three sentences on the angle and who it's for. Usually the best value for the effort.
- An outline. Headline, then bullet points in order. The kernel follows the structure and covers every point.
- An existing article. Pasted whole, it's treated as source material and rewritten in the voice (KB-504).
- A research outline. When Research has run, its outline is the brief; you don't write one.
When Auto-Pen builds the brief itself, it adds your positioning, the mention policy, and the sources Research found. When you send a brief directly (run_kernel { input }), it's sent as-is.
Things that help
- Name the reader in one line: "for a founder who's never hired a PR agency."
- State the claim, not just the topic: "argue that wholesale wire pricing is the only honest model."
- Give the numbers you want used, with their sources. The kernel doesn't invent figures, so a brief without numbers produces a piece without numbers.
- Say what to leave out. "Don't compare to Competitor X."
- Set a length if it matters: "about 900 words." Without one the kernel sizes to the material; a thin brief gets a short piece, which is right.
Asking for a shape
A shape written into prose ("use a bulleted list here") is one instruction among many and gets followed about a quarter of the time. If structure matters, use a template (KB-208): a template says which sections are headings, lists, tables, or prose, and the platform holds that shape as data rather than as a request. Templates bind to a collection, a post, or a seer.
Behind the scenes a template reaches the kernel as a skeleton: a list of blocks (heading, list, table, paragraphs, literal) in order, sent as data rather than as a sentence in the brief. A literal block is preserved byte for byte; a paragraphs block guarantees no list in that section, which turns out to be the harder half of the problem. A template is the way to ask for one from the app. run_kernel accepts both, with or without article_id: name a template and it fills the shape for you, or send a skeleton yourself when you are imposing a structure on material that does not exist yet.
The same guard works in reverse when a kernel edits an article that already exists: the platform reads the article's current shape and sends it as the skeleton, so headings keep their exact wording and a list or a paragraph stays what it was.
Calling the kernel directly
run_kernel takes one input field and a word for how to read it, rather than a choice between two fields:
| Field | What it is |
|---|---|
input | The text to write from, or your own post to regenerate. Required unless you pass article_id, which writes from that article's own content. Up to 200,000 characters. |
content_kind | How to read it: instruction (direction to write by), article / outline / research / notes (source material, turned into a faithful brief first; your own finished post is article), or auto. |
skeleton | The shape as data: headings, lists, tables, fixed text, prose. |
template | Name a template instead, and it fills the shape, the length and the brief structure for you. |
target_word_count | The word budget. Read back afterwards, within a tolerance. |
voice | The publication's person (third, we, I) and whether first-hand experience may be stated as fact. |
entities | Named-entity handling as data: each name with a treatment (never, mention_once, mention_often, lead_company) and whether it may be linked. Use this instead of writing "don't mention X" into the prose. |
label | A free-form tag for your own segmentation. It changes nothing about the writing. |
max_iterations | Rounds of write, rules and jury, one to five. |
Your own post is not edited in place: like any source material it is broken down into a brief and generated fresh. Its shape is always kept: headings stay, and its tables, images, code, quotes and references are held and put back under the heading they sat under.
Anything you leave out falls back to the endpoint's standing defaults (KB-407).
What not to do
- Don't describe the machinery ("the sections below are generated separately"). The kernel will relay it to the reader.
- Don't forbid a phrase by quoting it. A prohibition that quotes the phrase plants it.
- Don't ask for a word count far above the material. A 20-word brief asked for 900 words gets 880 invented ones.