brief-writer

---
name: brief-writer
description: Turns a vague request into a ten-slot brief any AI can follow, so the first answer is the one you wanted. Use before any AI request that matters.
---

# Tell an AI what you want and get it right first time

Describe the job in plain words. Get back a paste-ready brief, its examples and the settings.

## Claude does

1. **Collect four inputs and refuse to guess them:** who it is for, what good looks like, one real sample input, how it will be judged. Anthropic traced a wasted research run to the bare brief "research the semiconductor shortage": agents chased the wrong crisis and duplicated each other.
2. **Fill ten slots in this order:** role, task context, tone, rules, examples, input data, request, "think step by step", output format, prefill. Input before request: Anthropic measures question-last as up to 30 percent better on multi-document inputs. Over 20,000 tokens counts as long.
3. **Write 3 to 5 examples**, relevant, different, one shape, each in `<example>` tags. Use 6 for categories and shuffle their order, or the model learns the order not the features.
4. **Turn prohibitions into instructions.** Not "do not list game names" but "only discuss the console, the maker, the year and total sales". Ban only for safety or a strict format, and say why.
5. **Pick settings from the job:** factual 0.1 / 0.9 / 20 (temperature, top-P, top-K), drafting 0.2 / 0.95 / 30, creative 0.9 / 0.99 / 40, zero for one correct answer.
6. **Add the escape hatch, word for word:** "If you're unsure about any aspect, say I don't have enough information to confidently assess this."
7. **Refuse to invent** samples, names or figures. Leave `[ ]` for the user.

## Then Codex does

Assembly. The slots are decided, so ordering blocks, wrapping input in the XML shape and writing the settings sheet and log is mechanical bulk. Claude fills {JOB}, {SLOTS}, {EXAMPLES}, {OUTPUT_FORMAT}, {SETTINGS} into CODEX.md, then:

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

## Claude checks

1. Ten slots in order, input before the request, format near the end.
2. Three to five examples (6 for classification), one shape, categories shuffled.
3. No ban left where an instruction would do.
4. Nothing invented: every name, number and quote traces to the user's input, gaps as `[ ]`.
5. Escape-hatch sentence present, word for word.
6. Log carries name and version, goal, model, temperature, token limit, top-K, top-P, prompt, output.

Any check fails: name it, return the brief, rerun once. Failed twice, Claude finishes it.

## Rules
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.
- One job per brief, and version every brief you keep.
- Say what to do, not what to avoid.

## If Codex is not installed
Claude assembles the four files itself and says so.

## Built from
- Anthropic prompt engineering tutorial, https://github.com/anthropics/prompt-eng-interactive-tutorial, 38,070 stars (api.github.com): the ten-slot order.
- Anthropic prompting best practices, https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices: the 30 percent measurement.
- Google and Kaggle prompt engineering whitepaper, https://www.kaggle.com/whitepaper-prompt-engineering: sampling numbers, prompt log.
- Anthropic multi-agent research system, https://www.anthropic.com/engineering/multi-agent-research-system: the bare-brief failure.
- Anthropic reduce hallucinations, https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations: the escape-hatch wording.

# Brief writer - Codex task

You are assembling a finished prompt brief from parts that have already been decided. You are not the author. Do not improve the wording.

## You are given
- {JOB} one line saying what the brief is for.
- {SLOTS} ten labelled blocks of text: role, task context, tone, detailed rules, examples, input data, the immediate request, thinking instruction, output format, prefill. Any block may be empty.
- {EXAMPLES} between 3 and 6 worked input and output pairs.
- {OUTPUT_FORMAT} the shape the finished answer must take.
- {SETTINGS} the chosen temperature, top-P, top-K and token limit.

## Produce
Four files in the working folder, nothing else.

1. `brief.md` - the ten slots under one heading each, in the order listed above. Input data wrapped exactly as:
   `<documents><document index="1"><source>filename</source><document_content>...</document_content></document></documents>`
   Each example wrapped in `<example>` tags, all of them inside one `<examples>` block. The request comes after the input data. Output format sits second from last, prefill last.
2. `brief-short.md` - the same brief with the tone, thinking and prefill slots removed, for quick jobs. Same words, nothing rewritten.
3. `settings.md` - three rows: factual 0.1 / 0.9 / 20, default 0.2 / 0.95 / 30, creative 0.9 / 0.99 / 40, plus a token limit column. Mark the row matching {SETTINGS} as chosen.
4. `log.md` - a table with these rows: prompt name and version, goal, model and version, temperature, token limit, top-K, top-P, full prompt text, output. Set version 1.0 and leave the output row blank.

## Rules
- Copy the supplied text exactly. No rewriting, summarising, tidying or improving.
- Never add a fact, name, number, quote or example that is not in the inputs. Where something is missing, leave `[ ]`.
- The request never appears before the input data.
- Keep any "If you're unsure" sentence intact, character for character.
- If a slot is empty, keep its heading and put `[ ]` underneath. Do not fill it.
- British English. No em dash characters anywhere.
- Do not create, move or delete any file beyond the four named above.

## Return
Print to stdout:
- the four absolute file paths;
- the headings of `brief.md` in the order they appear;
- the number of `<example>` blocks found;
- the count of `[ ]` gaps across all files;
- the line number where the request block starts and the line number where the input data block starts;
- the first ten lines of `log.md`.