You send a manager a list of at-risk deals. They ask why one is on the list. If your answer is "the model scored it 0.72", the conversation is over, and so is the credibility of every future list. The real unit of work is the sentence under each flag that lets somebody argue with it.
By the end of this lesson you can: write a risk rule that names a field, a comparison and a threshold you chose; make every flag emit an evidence line; and produce a deal card a manager reads in ninety seconds without mistaking it for a verdict.
Rules first, in a file, before any run
Write 40-reference/risk-rules.md, versioned, before you ask for anything. Cowork carries no
memory between sessions. The rules file is the memory.
Shapes that work, with the thresholds left to you:
| Rule | Shape | The threshold you must choose |
|---|---|---|
| stage age | days_in_stage above N times the segment norm |
the multiple |
| overdue | open stage and close_date before the run date |
none, this one is binary |
| engagement gap | no two-way customer activity in N days on a deal above X | N and X |
| single thread | one contact with activity on a deal above X | X |
| repeat slip | close_date moved more than N times in the snapshot history |
N |
| no next step | next_step blank, or a date inside it that has passed |
none |
| stated blocker | a call note contains an explicit blocker the stage does not reflect | which words count |
Segment norms for stage age are in the data dictionary (DATA-DICTIONARY.md in your pack's data
folder): SMB about 18 days, Mid-Market about 32, Enterprise about 48. One flat number across segments is the most common way this rule produces
noise: a 60-day Enterprise deal is normal and a 60-day SMB deal is not.
State your norm basis in the rules file, in one line. "Segment norm as published in
DATA-DICTIONARY.md" is a different basis from "the observed mean days_in_stage for that
segment" and from "the observed median for that segment and stage", and the three give different
multiples on the same deal. None of them is wrong. An unstated basis is, because two people then
reproduce different numbers from the same file and neither can find the disagreement. Everything
in this lesson uses the published segment norms.
Every flag emits an evidence line
The evidence line has exactly three parts:
<rule name> | <the field or record that fired it> | <the value>
For example:
R1 stage-age | opportunities.days_in_stage vs Mid-Market norm 32 | 214
R2 overdue | opportunities.close_date vs run date 2026-08-02 | 2026-06-23
R3 gap | last two-way activity on OPP-006969 | 2026-06-16, 47 days
Three tests a flag has to pass before it goes in the pack:
- Can a person check it in under a minute without asking you? The evidence names the file, the field and the value, so yes.
- Can a person disagree with it? "32 days is the wrong norm for this segment" is an argument about the rule, which is productive, not about the output.
- If it is wrong, does the fix land in the rule? If the only fix is deleting the row, the flag was an assertion, not evidence.
A risk output without evidence lines is rejected in this module. Not a style preference: it is the difference between a pack that changes somebody's Tuesday and a pack that gets skimmed.
The deal card, and its last line
One card per flagged deal. You write each card yourself; a seed layout ships in
templates/M6/deal-card.md of your practice pack. Fixed sections:
Deal, account, owner
Stage, amount in local currency and USD, forecast category
Age in stage, against the segment norm
Days since last two-way customer activity
Next step, as recorded
Flags, each with its evidence line
Corroboration from notes, quoted, with the filename
What the data does not tell you
The last section is the honesty gate, and it is required. Without it the card is a verdict, and a manager acts on a verdict. With it the card is an inspection, and a manager asks a question. It is also the easiest section to write badly: "further information may be required" is not a sentence. The good version names a specific unknown and who could answer it.
Try this now: three rules, one deal, one card
About nine minutes. This is the exercise scaled up by the exercise sheet in labs/LAB-06 of your practice pack (start with its README).
You are the AE covering EMEA logistics at Talvera. Monday 2026-08-02. Your manager has stopped
asking "how is Selby going" in the meeting and started asking it in writing, which is worse. You
have opportunities.csv, accounts.csv, activities.csv and the call notes folder, all from
your pack's data folder.
- Create
40-reference/risk-rules.mdfromtemplates/M6/risk-rules.mdin your practice pack. - Write three rules with your own thresholds: stage age, overdue close date, and engagement gap. Each needs a name, a field, a comparison, a threshold, and the evidence line it emits.
- Fill the gaps in the starter brief below and run it against opportunity
OPP-006969. - Read
notes/call-notes/call-selby-supply.txtyourself. Add one quoted line of corroboration to the card, with the filename. - Write the "what the data does not tell you" section by hand. Do not delegate it. It is the one place in the card where you are the source.
- Compare against the reference card below.
Starter brief (fill the gaps marked <<...>>)
OUTCOME
Produce one deal inspection card for OPP-006969.
INPUTS
10-data/opportunities.csv, 10-data/accounts.csv, 10-data/activities.csv
10-data/notes/call-notes/
Rules: 40-reference/risk-rules.md, rules R1 to R3.
OUTPUT SHAPE
30-output/pipeline/deal-cards/OPP-006969.md
Sections in this order: header, position, flags, corroboration, what the data
does not tell you.
Every flag prints on its own line as:
<<state the three parts of the evidence line format>>
CONSTRAINTS
Run date is 2026-08-02.
The segment norm for stage age comes from <<where, and how do you get the
segment for this deal?>>.
For the engagement gap, count only <<which activity rows count as two-way
customer contact, and which do not?>>.
Convert the amount to USD using the account's billing currency as the authority.
Do not write anything to any file in 10-data/.
DEFINITION OF DONE
Every flag has an evidence line naming a field and a value.
The corroboration section quotes the source file by name or says "none found".
The final section is present and is not empty.
EXCEPTIONS RULE
<<what happens if a rule cannot be evaluated, for example because the deal has
no activity rows at all?>>
Stuck? Open these in order
Hint 1 (Concept)
The card is a by-product you throw away next week. The real output is the rules file, and the test of a rule is whether somebody who disagrees with the flag can point at the part they disagree with. Write the rule so it has parts.
Hint 2 (Move)
For stage age you need the account's segment: join opportunities.account_id to
accounts.account_id, read accounts.segment, then compare days_in_stage against the norm for
that segment (SMB about 18, Mid-Market about 32, Enterprise about 48, from DATA-DICTIONARY.md).
For the engagement gap, activities.csv has a related_type column: filter to
related_type = Opportunity and related_id = OPP-006969. Then look at what is left before you
take the maximum timestamp, because not every row in it is a customer conversation.
Hint 3 (Shape)
A correct answer fires more than one of your three rules, and independently: one about how long it has sat, one about a date that has passed, one about silence. If only one fires, check whether you wrote one compound rule instead of three.
The stage-age multiple here is high but not the highest in the file, so a threshold set to catch only the worst deal misses this one. Set it at the level you would actually inspect at.
Your "what the data does not tell you" section should hold at least one thing the call note tells you that no CSV column holds. If it only says "we do not know if it will close", write it again.
Reference card
# OPP-006969, Selby Supply Chain BV
Account ACC-02995, Netherlands, Mid-Market, Logistics. Owner Bettina Farrow.
## Position
Stage Technical Validation
Amount 54,000 EUR (58,320 USD at 1.08)
Forecast Commit # self-reported, see risk-rules.md section 0
Age in stage 214 days
Close date 2026-06-23
Next step Waiting on their IT security review
Last two-way 2026-06-16
## Flags
R1 stage-age | opportunities.days_in_stage vs Mid-Market norm 32 | 214 (6.69x)
R2 overdue | opportunities.close_date vs run date 2026-08-02 | 2026-06-23, 40 days past
R3 gap | last two-way activity on OPP-006969 | 2026-06-16, 47 days
## Corroboration
notes/call-notes/call-selby-supply.txt, written by the deal owner:
"Three gates. Legal (done, months ago). Data protection (done). Infrastructure
security, which is one contractor two days a week and a backlog. Nobody in the
building owns the third gate."
"close date on the record reads 2026-06-23 and that date has been and gone."
The note independently confirms R2, and gives R1 a cause: the deal is not stalled
on our side of the table and it is not stalled on price.
Worth reading next to the header: the record carries forecast_category = Commit
on a deal whose close date passed 40 days ago and which has sat in one stage for
214 days. This card does not treat that as a flag, because forecast_category is
a field somebody sets rather than something that happened. L6.4 is about the
difference.
## What the data does not tell you
- Whether the third approval gate has an owner now. No field in the CRM holds
this. Only the deal owner can answer it, and the answer is the deal.
- Whether the budget is real. The note records the champion saying it is funded
and declining to say from where. That is not in any column.
- Whether 214 days in Technical Validation is a dying deal or a slow procurement
cycle at an account that will eventually buy. The record cannot separate those
two, and this card does not try.
Your card may differ, and still be right. A stage-age threshold of 3x rather than 2x still flags this deal, and a 30-day engagement gap threshold rather than 45 still flags it, so your flags will match even if your numbers differ. Your multiple will differ from 6.69x if you used observed means or medians rather than the published segment norms, a legitimate basis as long as your rules file names it.
On the engagement date, this deal is unusually forgiving: the most recent activity row of any
kind and the most recent two-way customer contact are the same row, ACT-0043361 on 2026-06-16,
so a careless rule and a careful one agree here. A date later than 2026-06-16 means you read
another deal's rows. Counting only Meetings and Demos gives 2026-05-22 and a 72-day gap,
defensible if your rule says so. The two rules diverge badly on a different deal, and L6.4 is
that deal.
Worth knowing: the three flags took seconds and were already visible in three columns. The line that changes your manager's Tuesday came out of a text file no rule can read, which is why the card has a section only you can write.
What you keep
40-reference/risk-rules.md, version 1, with three rules and your thresholds.30-output/pipeline/deal-cards/OPP-006969.md, your first card.
Check yourself
- A risk output arrives with a column
risk_scoreand no evidence. Name the minimum change that makes it usable, and say why raising the score threshold is not it. - Your stage-age rule uses one flat threshold of 60 days across all segments. Which segment does it under-flag and which does it over-flag, and what does that do to the credibility of the pack?
- A card's final section reads "further analysis may be required". Rewrite it for a deal where the champion has gone quiet and the economic buyer has never been on a call.
Where this goes next
L6.4 hunts a false positive in these rules, changes the rule rather than the output, and assembles the pack a manager reads in five minutes.