Operator craft

Write better AI task briefs

By Justin Helmer · 8 August 2026 · ~15 minute read

Most “the agent failed” stories start as vague human briefs. Models fill gaps with guesses. Coding agents invent success. This guide is a reusable brief format used on chatagent.ca projects and Continuum seals.

The six-block brief

1. Goal, one sentence, observable outcome.
2. Why now, context in three lines max.
3. Inputs, paths, URLs, pasted excerpts (no secrets).
4. Constraints, stack, style, banned actions, privacy.
5. Done checks, bullets a skeptic can verify.
6. Handoff, who receives what next.

Copy-paste template

GOAL:
WHY NOW:
INPUTS:
CONSTRAINTS:
- no network unless stated
- no secrets in chat
DONE CHECKS:
- [ ] …
CONTINUUM CLAIMS (optional):
- file_exists: …
- file_contains: …
HANDOFF:
- next owner:
- packet:

Examples

Documentation brief

Goal: “Publish a 800+ word guide on X with internal links.” Done checks: word count, TOC, author box, sitemap entry. Constraints: original prose, no scraped copies.

Code brief

Goal: “Add Continuum sample claims for the login module.” Done checks: self_check passes, capsule seals green, README note. Constraints: stdlib only.

Review brief

Goal: “Δ9RA pass on this release note.” Done checks: list of overclaims removed, evidence links added.

Why this helps AdSense-quality publishing too

Clear briefs produce specific articles and tools. Thin sites often ship features without explaining them. On chatagent.ca, every major tool should earn a guide with templates, limits, and human responsibility language.

Worked example: a documentation brief

This is the shape that works for a writing task. It is deliberately boring: the agent should not have to guess what “better” means.

GOAL:
Rewrite guides/example.html for a reader who has never used the tool.

WHY NOW:
The current page assumes jargon and has no worked example.

INPUTS:
- guides/example.html (current file)
- /guides/lygo-lattice-overview.html (tone reference)
- the tool's public page (link in the current file)

CONSTRAINTS:
- Keep every existing internal link.
- Do not invent commands or screenshots.
- Return the full HTML file, not a fragment.
- No new dependencies.

DONE CHECKS:
- [ ] The page explains one task from start to finish.
- [ ] Every command shown was run, or is labeled as an example.
- [ ] At least one table and one FAQ section.
- [ ] Every internal link resolves.
- [ ] Byline and review date are visible.

HANDOFF:
- Next owner: human reviewer.
- Packet: the file path, the diff, and the check output.

Why it works: the goal is observable, the inputs are named, the constraints prevent the common failure (a rewrite that deletes links), and the done checks can fail. A brief whose checks cannot fail is a wish.

Worked example: a code brief

GOAL:
Add a --dry-run flag to tools/verify.py. It must print the files it would check and write nothing.

INPUTS:
- tools/verify.py
- tests/test_verify.py

CONSTRAINTS:
- Python standard library only.
- No network calls.
- Do not change the default behavior.
- Keep the existing CLI flags working.

DONE CHECKS:
- [ ] `python tools/verify.py --dry-run` exits 0.
- [ ] The dry run creates or modifies no files.
- [ ] `python -m pytest -q` passes.
- [ ] README documents the flag.
- [ ] A test covers the dry-run path.

HANDOFF:
- Next owner: verifier.
- Packet: diff, test output, and the exact commands run.

The important line is “write nothing.” It gives the reviewer a negative check, not just a happy path. A coding brief without a “must not change” line invites collateral edits.

Worked example: a review brief

GOAL:
Review the release note in releases/v2.3.md for overclaims.

INPUTS:
- releases/v2.3.md
- the public changelog
- the test output for v2.3

CONSTRAINTS:
- Do not add new claims.
- Do not rewrite the whole note.
- Mark each removal with the sentence it replaced.

DONE CHECKS:
- [ ] Every factual claim has a link or a test reference.
- [ ] Every opinion is labeled as an opinion.
- [ ] The list of removed overclaims is included.
- [ ] The note still fits on one screen.

HANDOFF:
- Next owner: publisher.
- Packet: the edited note and the removal list.

A review brief is not “make it better.” It names the failure (overclaim), the evidence, the boundary (no new claims), and the record (removal list).

How to write a done check

A done check is a test that a skeptic can run without asking the author what they meant. Use the smallest check that actually proves the claim.

If you cannot name a check, the task is not ready. That is not a reason to skip the check; it is a reason to reduce the task until it has one.

Constraints that actually constrain

• Environment: which machine, which shell, which runtime, which browser.
• Files: what must not be touched, deleted, renamed, or reformatted.
• Network: allowed or forbidden; if allowed, which hosts.
• Dependencies: stdlib only, existing lockfile, no new packages.
• Voice: audience, reading level, banned phrases, required terminology.
• Privacy: what must be redacted, what must never be pasted, where output may be stored.
• Output: full file, patch, diff, JSON, or a short summary, pick one.
• Time: a deadline is a constraint; “when you can” is not.

More constraints are not automatically better. A brief with twenty rules is hard to follow and easy to game. Pick the five that prevent the failure you actually fear.

Common failure modes

Review the output against the brief

Do not review the output in the abstract. Read it against the brief, line by line.

1. Goal: does the output do the one thing the goal asked for?
2. Constraints: did it touch a forbidden file, add a dependency, or change the voice?
3. Done checks: run each one. Do not accept “should pass.”
4. Diff: read the actual change, not just the summary.
5. Secrets: scan the output for keys, tokens, private URLs, and personal data.
6. Next step: is the handoff clear enough for a stranger?

If a check fails, return the check and the evidence, not a vague “try again.” A retry without a new constraint is a coin flip with a nicer interface.

When the brief is the wrong tool

For a one-line question, a brief is overhead. For exploratory work where the destination is unknown, write a short research brief with a time box and a decision to be made, not a fake specification. The brief is for work that can be finished and checked, not for thinking out loud.

FAQ

How long should a brief be?

As long as it takes to make the goal, inputs, constraints, and checks unambiguous. Most are half a page. A two-page brief for a ten-minute task is a sign the task is not understood yet.

What if the agent asks a question?

Answer it in the brief, not only in the chat. The next agent will not see the chat. A question is a signal that the brief had a gap.

Can I use this with a champion persona?

Yes. The champion frames the role; the brief defines the job. The summon guide covers the role side.

What if there is no test?

Use an observable check: a URL that returns 200, a screenshot at a named size, a file hash, a required sentence, or a named human sign-off. “Looks good” is not a check.

How do I handle secrets?

Redact them before the brief. The redaction guide has the checklist. A brief is not a secure channel.