Writing a brief for an AI feature
A brief is the short document that says what a feature must do and how you will know it works. It matters because an AI feature with a vague brief can look finished and still fail in front of customers.
In this module the invented Fernside Library asks for a help assistant. The first email says: "Can we have a chatbot that answers questions about opening times and fines? It should be good."
By the end of this lesson
Note
I can turn a request into requirements and a way to know it works.
Key words
| Word | What it means | Example |
|---|---|---|
| Brief | the short document that says what to build | |
| Requirement | one thing the feature must do or respect | |
| Limit | a number the feature must stay within | at most 40 words |
| Measure | a number that says how good the answers are | |
| Fallback | what users get when the feature cannot answer |
The cells students fill in are left blank in this preview.
A request is not a brief
A request says what somebody wants. It does not say who uses it, what it must never do or when it counts as finished.
You turn it into a brief by asking the questions it leaves open. Ask them before you build, because every answer changes what you build.
Worked example: the library's request
| The request says | The question it leaves open |
|---|---|
| A chatbot | Who asks, and on which page? |
| Opening times and fines | Which other questions will people ask? |
| It should be good | How many wrong answers can we accept? |
| Nothing about size | How long may an answer be? |
| Nothing about money | What may one day of use cost? |
The cells students fill in are left blank in this preview.
A measure of good has a number
"Good" is an opinion. "9 answers in 10 hold the right figure" is a measure: two people can check it and agree.
A measure needs a set of test questions and a rule that marks each answer. You build both in the next lesson. For now the brief only has to say what the number will be.
Limits, cost, privacy and a fallback
Four more parts are often left out. A limit such as 40 words. A cost cap for one day. A privacy rule that says what is never stored. A fallback for the day the model does not answer.
Add an owner, a person who decides when the numbers are not met.
A common mistake
Warning
Many people think the model will make a vague brief clear. It will not. If nobody can say which answer is wrong, nobody can say when the feature works. Write the number before you build.
Write the brief checker, part 1
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const fs = require(\"fs\");' '// The request as the library sent it, turned into parts.' 'const brief = {' ' users: \"Library members asking about opening times and fines\",' ' tasks: \"Answer questions from the fact sheet\",' ' limits: \"Answers should be short\",' ' measure: \"Answers should be good\",' ' cost: \"\",' '};' 'fs.writeFileSync(\"brief.json\", JSON.stringify(brief, null, 1));' > brief.js"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Write the brief checker, part 2
docker exec -w /home/node/project agent sh -c "printf '%s\n' 'const REQUIRED = [\"users\", \"tasks\", \"limits\", \"measure\", \"cost\", \"privacy\", \"fallback\", \"owner\"];' 'const NEEDS_NUMBER = [\"limits\", \"measure\", \"cost\"];' 'const missing = [];' 'const vague = [];' 'for (const part of REQUIRED) {' ' const text = (brief[part] || \"\").trim();' ' if (text === \"\") missing.push(part);' ' else if (NEEDS_NUMBER.includes(part) && /[0-9]/.test(text) === false) vague.push(part);' '}' 'console.log(\"Missing parts:\", missing.join(\", \"));' 'console.log(\"Parts with no number:\", vague.join(\", \"));' 'console.log(missing.length + vague.length === 0 ? \"The brief is ready.\" : \"The brief is not ready.\");' >> brief.js"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Check the library brief
docker exec -w /home/node/project agent node brief.jsShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
What the Run prints
| Line | What it says |
|---|---|
| Missing parts | cost, privacy, fallback, owner |
| Parts with no number | limits, measure |
| Last line | The brief is not ready. |
The cells students fill in are left blank in this preview.