# The Brief Standard

Version 1.1 · https://newworkprojects.com/brief-standard · CC BY 4.0

## Why a standard

For twenty years, tickets were read by people who knew the product. When a story said “export reports”, the engineer knew which reports, walked over and asked about the format, and caught the permission question in review. The ticket was a reminder of a conversation.

Agents don’t have the conversation. They read what is written, fill every gap with the most plausible answer and ship it with confidence. The failure isn’t bad code. It is a good implementation of a guess.

The Brief Standard is a small, open format for work that is written to be built by someone who cannot ask: an agent, a contractor, a new teammate, or you in six months. It is plain Markdown, so it works in any tool. NEWWORK Projects scores it, but you don’t need NEWWORK Projects to use it.

### Five principles

1. **Write for a reader who cannot ask.** Everything the builder needs is in the brief or linked from it.
2. **Ask, don’t guess.** What the author doesn’t know becomes an open question or an assumption to keep or strike, never a confident answer.
3. **Context is a link, not a memory.** Name the repository, the file, the document, the screen.
4. **Done is proven.** Every acceptance check is observable and is ticked with the evidence that proves it.
5. **Small enough to prove.** If the checks don’t fit on a screen, it is an epic.

## The format

A brief is Markdown with `##` sections. Headings are in English in every language so that tools find them; the text is in whatever language the team writes. Sections that don’t apply are left out, not filled with “N/A”.

### Stories and features

| Section | What it says |
| --- | --- |
| **Intent** | Who wants what, and why, in a sentence or two. The tie-breaker for every decision the brief doesn’t cover. |
| **Context** | Where the work happens: repositories, files, screens, documents, links, and what exists already. |
| **Behaviour** | What happens, step by step, numbered. |
| **Edge cases** | Empty, huge, concurrent, offline, wrong role. |
| **Constraints** | What must not change: contracts, performance budgets, permissions, things other code relies on. |
| **Out of scope** | What a well-meaning builder would add, and must not. |
| **Open questions** | What the author doesn’t know yet. One bullet each. |
| **Assumptions** | What the author decided without being told, to keep or strike. |
| **Acceptance checks** | Observable statements, one per line. |

### Other types

- **Bugs:** Steps to reproduce, Expected, Actual, plus Context (version, browser, account) and Acceptance checks. “Fixed when” works as a heading for the checks.
- **Tasks:** What to do, concrete enough to start right away, plus Context and checks.
- **Epics:** Intent, Scope and Capabilities, with the stories below them carrying the checks.
- **Initiatives:** Intent, Success measures, Milestones and Risks.
- **Change requests:** a story with who asked for it, their reference and the price, decided before the work starts.

## Acceptance checks

A check is a statement someone else can observe to be true. It is not a task (“add an export button”) and not a wish (“should be fast”).

- One check per line, under a heading such as `## Acceptance checks`.
- Concrete and observable: “10,000 rows export in under 2 seconds”, not “performant”.
- Given / when / then is welcome, not required.
- Include the permission check. It is the one people forget and agents never guess right.

Tools recognise a check that isn't observable by its wording. A check that **starts like an instruction** (Add, Implement, Create, Build, Make, Fix, Refactor, Write, Set up, Integrate) is a task. A check that **leaves the result to taste** (fast, easy, user-friendly, intuitive, correctly, properly, as expected, robust, better, “it works”) is a wish, unless a number pins it down. “Export is fast” is a wish; “Export is fast: 10,000 rows in under 2 seconds” is a check.

A check is **passed** only with **evidence**:

| Evidence | Example |
| --- | --- |
| Pull request | `https://github.com/acme/app/pull/381` |
| Commit | `https://github.com/acme/app/commit/9f2c1e7` |
| Test run | a CI link, or the test and its result: `npm test: 48 passed` |
| Link | the deployed page, a recording, a document |
| Confirmed | a person’s tick without evidence, recorded with their name |

Agents must attach evidence to pass a check. A failed check says what failed.

## Testing

Every acceptance check is a test case: it says what has to be true. There is no second list of test cases next to the checks, because two lists drift apart. How a check is proven depends on its kind.

- **Automated, by default.** The builder writes a test for each check in the repository, where it keeps running after the ticket is closed. The test is named after the check, with the ticket key and the check’s number, so a failing test points back to what it guards and anyone can find the tests of a ticket: `test('PROJ-42 check 2: the totals match the monthly overview', …)`.
- **Ticked with the test.** The check is passed with its test as evidence: the test and its result, such as `src/reports/hours.test.ts › PROJ-42 check 2: passed`, and the CI run when there is one. When the test fails, the check fails, with what failed.
- **Manual, when it can’t be automated.** How an email looks in Outlook, or whether a flow makes sense to a first-time user. The check ends in `(manual)` and says what a person looks at: “The reminder looks right in Outlook and Gmail (manual)”. An agent may prepare a screenshot or a recording; a person passes the check.
- **More tests are welcome.** Tests for edge cases and regressions beyond the checks are good practice. They don’t replace a check, and a check isn’t passed by a test of something else.

## Open questions and assumptions

Open questions are the most important part of a brief, because each one is a guess that didn’t happen.

```md
## Open questions
- Which separator should the file use: comma or semicolon?
- [x] Do managers see their team's hours? Yes, team only.
```

- Every bullet under **Open questions** counts as open, unless it is ticked (`- [x]`) or says “None”.
- A brief with an open question is **not ready**, whatever else it says.
- **Assumptions** are listed, not hidden in the text. Keep one and it becomes part of the brief; strike it and it leaves.
- Names, numbers, limits and exact wording are never assumed. They are questions, or a `[to confirm]` placeholder.

## Readiness

Readiness is a score from 0 to 100 that says whether a brief can be handed to an agent. It checks the shape of the brief, not whether it is right.

| Part | Points | Counts when |
| --- | --- | --- |
| Intent | 25 | 40 characters or more under an Intent heading or before the first heading, or 80 characters of text anywhere when the brief has no Intent heading. |
| Acceptance checks | 30 | At least one check, and every check observable. While some checks are tasks or wishes, 15. |
| No open questions | 25 | No open bullet under Open questions. |
| Context | 20 | Text under a Context heading, a URL, or a file path in backticks such as `src/reports/HoursReport.tsx`. |

A brief is **ready for an agent** at 100: all four parts. 50 or more is close; below 50 an agent will guess.

#### Headings that count

| Part | Headings (case-insensitive, English or German) |
| --- | --- |
| Intent | Intent, Goal, Problem, Summary · Ziel, Absicht, Zusammenfassung |
| Context | Context, Background, Where, Steps to reproduce, Today, Repositories, Files, Links, References · Kontext, Hintergrund, Wo, Schritte, Heute, Dateien, Referenzen |
| Open questions | Open questions, Questions · Offene Fragen, Fragen |
| Assumptions | Assumptions · Annahmen |
| Acceptance checks | Acceptance criteria, Acceptance checks, Done when, Fixed when, Definition of done · Akzeptanzkriterien, Abnahmekriterien, Fertig wenn, Behoben wenn |

`**Bold lines**` on their own work as headings too. A plain line such as “Acceptance criteria:” does not: tools can’t tell it from a sentence.

## Verified done

Moving a ticket to Done is a claim. **Verified** is the proof:

1. Every acceptance check is passed with evidence.
2. No pull request linked to the ticket is still open.
3. No documentation update for it is still waiting for review, where the team uses them.

Anything missing is listed, so “Not verified” always says what to do next.

## An example

```md
## Intent
As a finance manager, I want to export one month of logged hours as a CSV,
so that payroll closes without retyping numbers.

## Context
- Report page: `src/reports/HoursReport.tsx`
- Totals come from `time_entries`; the monthly overview already sums them

## Behaviour
1. A manager picks a month and chooses **Export CSV**.
2. One row per person and day: date, person, project, ticket, hours, billable.
3. Members export only their own hours.

## Constraints
- The monthly overview and its totals stay exactly as they are.

## Out of scope
- Scheduled exports, email delivery, Excel (XLSX) files.

## Open questions
- [x] Separator? Semicolon: finance uses German Excel.

## Acceptance checks
- Given a manager, when they export March, then the file has one row per person and day
- The totals match the monthly overview
- A member cannot export someone else's hours
- 10,000 rows export in under 2 seconds
```

Readiness 100: an intent, context with file paths, four checks and no open question.

## Using it

- **In any tool:** copy the headings into your ticket template. Paste a ticket into the [Brief Checker](https://newworkprojects.com/brief-checker) to score it.
- **In NEWWORK Projects:** Write with Nova, drafts from notes and brainstorm plans produce briefs in this format, every ticket shows its readiness, and agents read the brief, write a test for each check and tick it over MCP (`pm-item-get`, `pm-brief-check`, `pm-check-tick`).
- **In your own tools:** the reference scorer, a command line, JSON Schemas and conformance cases are published as `@newwork/brief-standard` under the MIT license. `npx @newwork/brief-standard TICKET.md` scores a brief and exits with an error when it isn’t ready, so it can gate a pipeline. Another tool conforms when it gives the same answers for every case.
- **Templates:** the [Brief Library](https://newworkprojects.com/library) has a brief for each common kind of work.

## Version and license

Version 1.1, October 2026. The Brief Standard is published under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/): use it, change it and build tools for it, with a credit to NEWWORK Projects. Suggestions are welcome at hello@newworkprojects.com.

### Changes

- **1.1:** Acceptance checks that are tasks or wishes score 15 instead of 30 points, and the brief isn’t ready until they are rewritten. Checks can be marked `(manual)`, and a person passes them. New: Testing, with one test per check, named after it, as the evidence that passes it.
- **1.0:** First version.