A brief for work you will not watch

This is the one thing the whole product rests on. Everything else is settings.

A brief for work you are watching can be short, because you correct it as it goes. A brief for work you are not watching has to answer, in advance, every question the task will hit. There are five of them, and they are the same five every time.

The five things a brief has to say

The brief in lesson 2 has all five. Read it again and you can point at each one. That is the whole technique, and it is worth being boring about.

The sentence that saves the most time

If something is ambiguous or a file is missing, stop and tell me
rather than guessing. Do not invent numbers.

Left to itself a task will try to finish, because finishing is what it was asked to do. That instinct is right when the ambiguity is small and wrong when it is not. Telling it where the line is turns a confidently wrong deck into a short message asking a question.

Say how it should check itself

A task that verifies its own work is worth two that do not. The check has to be something concrete.

• "The row count in the combined sheet should equal the sum of the rows in the exports, minus the dropped ones. Tell me both numbers."
• "Total revenue in the summary must match the spreadsheet. Say so explicitly."
• "List any month that has no data at all."

These are not extra work for you. They are the difference between reading the result and auditing it.

Checking a brief before you send it

The panel beside this holds the sales brief and a checklist that looks for the five things, plus the two habits from this lesson. Press Run.

"""Check a brief for the five things, before you leave it alone.

This is a checklist, not a judge. It looks for the words that show
each of the five is present. A brief can pass this and still be
vague, but a brief that fails it will be guessed at.
"""

brief = open("brief.txt").read().lower()

LOOKS_LIKE = {
    "input":      ["folder", "file", "export", "from ", "in the"],
    "output":     ["spreadsheet", "summary", "document", "deck", "save", "write"],
    "rules":      ["column", "drop", "treat", "format", "must", "only"],
    "audience":   ["for a", "for the", "manager", "team", "reader"],
    "edge cases": ["missing", "inconsistent", "ambiguous", "no ", "if "],
}

for thing, words in LOOKS_LIKE.items():
    found = [w for w in words if w in brief]
    mark = "ok  " if found else "GAP "
    print(f"{mark} {thing:<11} {found[:3]}")

print()

if "stop" in brief and "guess" in brief:
    print("ok   it is told to stop rather than guess")
else:
    print("GAP  add: stop and tell me rather than guessing")

if any(w in brief for w in ("count", "check", "match", "state ")):
    print("ok   it is asked to check its own work")
else:
    print("GAP  ask it to restate a number you can verify")

print()
print("words:", len(brief.split()))

It found all five, and it caught something real: the brief from lesson 2 never asks the task to restate a number you can check. That is the gap this lesson opened with, and it is the line worth adding before the job is ever left alone.

Paste one of your own briefs in and see what it says. Most first drafts are missing audience and edge cases, in that order.

What not to put in

Do not describe the steps. Say what you want and what good looks like, then leave the how alone. A brief that says which button to press is a brief that breaks the first time the data is shaped slightly differently.