In Module 1 you ran a snapshot. In Module 3 you picked a workflow worth repeating. Now you write the thing that makes it repeatable. Your first attempt will be a sentence, because sentences are what people type.
A brief contains the four things a sentence leaves for the agent to decide: what counts as finished, what not to touch, when to stop, and what to do with the rows that do not fit. Either you decide those in advance, or something else decides them at run time.
What you will be able to do
- Write a seven-part brief and get a usable first result from it.
- Look at a failure and name which part of the brief it came from.
- Stop polishing phrasing, the smallest lever you have.
The seven parts
Same task, two ways, on the shipped data.
The request:
Give me a summary of the Oldcastle Leisure account.
The brief:
Outcome
A one-page renewal-ready snapshot of one account that a CSM can read before a
call without opening any file.
Inputs
10-data/accounts.csv fields: account_id, account_name, segment, industry,
country, region, owner, csm, contract_start_date,
arr_usd, currency, health_score, renewal_date, tier,
lifecycle_status
10-data/opportunities.csv fields: opportunity_id, opportunity_name, type, stage,
amount, currency, close_date, forecast_category
10-data/contacts.csv fields: contact_name, title, persona, last_activity_date
10-data/activities.csv fields: timestamp, activity_type, subject, owner, outcome
Account: ACC-02848.
Output shape
30-output/account-snapshot/<YYYY-MM-DD>-ACC-02848.md
Sections in this order: Account facts. Opportunity history (oldest first).
Contacts. Last five activities. Reconciliation. What the data does not tell you.
Constraints
Read-only. Do not modify anything in 10-data/.
Do not infer a value that is not in the files. Blank means blank, say so.
Every number carries the file and column it came from.
Never add a Renewal amount to a New Business amount: renewal amounts restate
current ARR (DATA-DICTIONARY.md, opportunities.type).
Definition of done
Every opportunity on this account appears exactly once in the history section,
and the Reconciliation section states the row count, the distinct
opportunity_id count, and whether they agree.
Stopping condition
If the row count and the distinct opportunity_id count disagree, do not choose
between the conflicting rows. Report both and continue with the rest.
Exceptions rule
Anything unresolvable goes to
30-output/account-snapshot/exceptions.csv with the row identifier and the
reason. Do not guess.
Longer, yes. But the length went into named files, named columns, a named output filename, and three rules for when something does not fit. Not adjectives.
Those last three sections earn their keep here. ACC-02848 has four opportunity rows but
three opportunities: OPP-007099 appears twice with different amounts
(answer-keys/PLANTED-ISSUES.md in your pack, which you open only after attempting the lab,
class duplicate-opportunity-rows). The request gets you a clean summary with a wrong total
and no warning. The brief cannot: the definition of done forces both counts onto the page,
and the stopping condition forbids picking a row.
Which of the seven parts was your last request missing?
Prompting, sized honestly
This is the only section in this course about phrasing, and it stays one section. Most of the discipline is choosing the right work (Module 3), judging the output (Lesson 3), and deploying responsibly (Modules 2 and 8). A course that is mostly prompt technique has mis-sized the problem.
Three techniques earn their place in revenue work. There is no fourth.
1. Give the shape of the output, not adjectives about it. "Comprehensive" describes a feeling. A section list, a column list and a filename describe an artifact. Reaching for an adjective means you have not decided what you want yet.
2. Give one worked example of a correct row.
Example of a correct history row:
| OPP-007468 | New Business | Closed Won | 55,000 USD | 2023-10-19 |
One line settles date format, money format, currency placement, column order and level of detail at once.
3. Say what to do when the data is ambiguous. The highest-yield sentence in any brief,
and Lesson 3's whole subject. "If two rows share an identifier and disagree, report both and
write the conflict to exceptions.csv. Do not choose."
Then stop. If the output is wrong, the fix is almost never a better adjective. It is a missing input, an unstated constraint, or a definition of done you never wrote. Open-ended tasks fail more often, and they fail bigger.
Both versions, run
Pass 1, the request. Back in seconds. Clean prose, three headings, a total: "total closed-won value 234,000 USD across 4 opportunities". Reads well. Both numbers are wrong, in different ways, and the page gives you no way to tell. I did not reply "are you sure?": that buys a confidence statement, not a comparison. The fix goes in the brief, not the chat.
Pass 2, the brief. Same folder, same files. The reconciliation section: four rows, three
distinct opportunity_id values, they do not agree. One line, and the summary becomes
something you can defend.
The stopping condition earned its place at once. OPP-007099 appears at 69,000 USD with
close date 2025-10-19 and at 55,000 USD with a blank close date. Without the stopping
condition, a helpful run picks one. With it, both rows go in the snapshot and the conflict
goes to exceptions.csv.
The reconciliation also surfaced something unasked: accounts.arr_usd here is 55,000,
matching one conflicting row and not the other. A signal, not a resolution. The row matching
ARR is the one missing its close date, so the evidence points both ways. The right output
raises the question and names who could settle it, instead of quietly picking for you.
And one number I refused to print: "total closed-won value". Three of the four rows are
type = Renewal, and renewal amounts restate current ARR rather than adding to it
(DATA-DICTIONARY.md in your pack's data folder). Summing them gives 234,000, which describes nothing. The brief now
says what may be totalled and what may not.
Your turn
You are the CSM covering Oldcastle Leisure Inc. Renewal date 2026-10-19, call this week. You want a snapshot you can regenerate every quarter, for any account, in under a minute. Budget six minutes. This produces the first file of your brief pack.
Everything this lesson uses came in the practice pack from the course page; if you have not downloaded it, do that first.
Setup: grant revenue-workspace/, the folder you built in Module 2, with the pack's dataset
copied into 10-data/ (accounts.csv,
opportunities.csv, contacts.csv, activities.csv). No connectors. Read-only. Have your
Module 2 CLAUDE.md in place.
Try this now
- Open
templates/M4/account-snapshot.brief.mdfrom your practice pack and fill the four gaps (starter below).- Save it as
20-briefs/account-snapshot.brief.md: this is a file you create, and it lives in your workspace from here on.- In a session, grant the folder and say only:
Run the brief in 20-briefs/account-snapshot.brief.md for account ACC-02848.Nothing else. If you have to add anything, the brief was incomplete, and that is the finding.- Open the output. Read the Reconciliation section first.
- Open
exceptions.csv. If it is empty on this account, your Exceptions rule or Stopping condition is not doing its job. Fix the brief, not the output.
The starter brief, with gaps marked:
# Brief: account snapshot
## Outcome
A one-page renewal-ready snapshot of one account that a CSM can read before a call
without opening any file.
## Inputs
10-data/accounts.csv, 10-data/opportunities.csv, 10-data/contacts.csv,
10-data/activities.csv.
<<GAP 1: name the exact columns you need from each file. Not "the relevant
fields". Column names.>>
Account: supplied at run time as an account_id.
## Output shape
30-output/account-snapshot/<YYYY-MM-DD>-<account_id>.md
Sections: Account facts. Opportunity history, oldest first. Contacts. Last five
activities. Reconciliation. What the data does not tell you.
<<GAP 2: one worked example row for the opportunity history section, showing
date format, money format and column order.>>
## Constraints
Read-only. Do not modify anything in 10-data/. Do not infer a value that is not in
the files; blank means blank.
<<GAP 3: the constraint that stops a wrong total on this data. Look at
DATA-DICTIONARY.md, opportunities.type, and at the currency convention.>>
## Definition of done
<<GAP 4a: the condition that makes the Reconciliation section non-optional. It
should force two counts to be printed and compared.>>
## Stopping condition
<<GAP 4b: what to do when those two counts disagree.>>
## Exceptions rule
Anything unresolvable goes to 30-output/account-snapshot/exceptions.csv with the
row identifier and the reason. Do not guess.
Stuck? Three hints, in rising order of help.
- Three of the four gaps make the output nicer. One makes it possible to tell that the output is wrong. A snapshot that reads beautifully and cannot be checked is the failure this module exists for.
- Before writing GAP 4, count by hand for
ACC-02848: the rows inopportunities.csvfor that account, and the distinct values ofopportunity_id. Then write the instruction that makes the agent print those two numbers every time, for any account, unasked. - GAP 4a should name two counts and require them printed and compared, not just computed.
GAP 4b should forbid a choice: report both rows, route the conflict to exceptions, never
pick the row that looks more complete. GAP 3 needs two sentences, one about
type = Renewalamounts and one about currency, becauseopportunities.amountis in the account's local billing currency whileaccounts.arr_usdis in USD.
What you should see on ACC-02848 (the filled brief ships as
templates/M4/account-snapshot.brief.md):
- Account facts: Mid-Market, Hospitality, 302 employees, United States, NA, owner Ursula Ulrich, CSM Helena Zabala, contract start 2023-10-19, ARR 55,000 USD, currency USD, health score 37, renewal date 2026-10-19, Tier 2, Customer.
- Opportunity history:
OPP-007468New Business Closed Won 55,000 USD 2023-10-19;OPP-007132Renewal Closed Won 55,000 USD 2024-10-19;OPP-007099Renewal Closed Won appearing twice, at 69,000 USD with close date 2025-10-19 and at 55,000 USD with a blank close date. - Reconciliation: 4 rows, 3 distinct opportunity ids, they do not agree.
exceptions.csv: at least one row,OPP-007099, reason: duplicate identifier with conflicting amount and one blank close date, cannot determine which row is authoritative.- What the data does not tell you: which of the two 2025 renewal amounts is correct; that no
renewal opportunity exists for the 2026-10-19 renewal date; that
health_score37 has no stated definition in the data.
Your run may differ in section order, table versus prose, activity count, exception wording,
and whether you note the account's declining seat utilisation. It may not differ here: a
missing Reconciliation section, or a run that silently picked one OPP-007099 row, means
the brief failed, however good the page reads. And GAP 3 must contain both rules from
DATA-DICTIONARY.md: renewal amounts restate current ARR and are never added to New
Business amounts, and never total across currencies without converting.
Worth knowing: the parts of a brief that feel like bureaucracy, the definition of done and the stopping condition, are the only two parts that can tell you the output is wrong.
What you keep
revenue-workspace/20-briefs/account-snapshot.brief.md, the first file of the brief
pack, runnable by naming the file, on any account id. Also keep the pass-1 output next to
the pass-2 output. You will need both in Lesson 2.
Check yourself
- A brief produced a snapshot that stopped after twelve of forty accounts and reported success. Which of the seven parts was missing? Name a second part that could also have caused it, and how you would tell them apart from the output.
- Your output has the right numbers and the wrong section order. Which part do you edit, and how much time should that take?
- Someone proposes fixing a recurring wrong total by adding "please be accurate and double-check your work" to the brief. What will that change, what will it not, and which part should they edit instead?
Answers
1. Definition of done: nothing stated the condition that makes it finished, so twelve accounts satisfied it as well as forty. The second candidate is the stopping condition: it may have hit something unresolvable and stopped correctly. The output tells them apart. Stopped with a named row and reason: the stopping condition fired, the system worked. Reported success with no reason: the definition of done was missing.
2. Output shape, in under a minute. Section order is the cheapest thing in a brief to change and the least important to get right first.
3. It changes the tone, not the total. Nothing in that sentence says which rows may be added to which, so the same wrong total comes back sounding more careful. Edit Constraints, naming the rule that makes the total wrong, and Definition of done, requiring the reconciliation that would have exposed it.
Where this goes next
Next lesson: the same brief, run with and without the folder context file.
Track labs: the exercise sheet in labs/LAB-04 of your practice pack (start with its
README). Part A runs three passes on this task and requires the account
chosen to contain one of the four documented duplicate opportunity ids, so the reconciliation
has something real to catch.