M01-L04 — Write an engineering brief
Outcome: Specify a bounded reporting task with context and observable acceptance criteria.
Start: M01-L03 and Chapter 3 original reporting resources.
A task brief connects an intention with a starting state and a result you can recognize. Separate goal from current behavior. “Identify replay inputs as synthetic in the explanatory report” is a goal. “The present report can be read without noticing its origin” is the current problem. Naming both helps the assistant avoid treating existing behavior as the requirement.
Include the exact checkpoint, relevant file paths, environment when it affects the task, supplied evidence, constraints, requested output, and acceptance criteria. Do not collect unrelated hardware details just to fill a template. For a report explanation, a serial port is unnecessary. For a cross-build, the full target configuration matters.
The worked brief requests a short plan and illustrative report lines, preserving values, validity, state names, and record order. It excludes firmware, timing, dependency, and fixture edits. It requires explicit synthetic labeling and forbids invented physical or executed-command claims. Those limits make the result small enough to inspect.
Acceptance criteria should distinguish a correct result from a plausible wrong one. Include a normal input and an invalid or unknown-origin case. Do not let the presence of a number turn an invalid sample into a claimed measurement. Assess the returned artifact yourself against the criteria; agreement from a second assistant is useful review input only when it adds evidence.
For the demonstration, transform the vague request in the editor, submit the completed brief with its actual relevant input, and review the resulting plan. A proposal for a cloud dashboard is outside this reporting task. Preserve interesting future ideas separately while completing the requested result.
D04. A goal, relevant context, constraints, and observable acceptance produce a reviewable task. The actual result is compared with acceptance.
Practice and completion
Complete the exercise, then compare your artifact with the separately distributed instructor answer. A lesson acknowledgment records your own progress; it does not certify that a physical test occurred.
Chapter 3. Resources: Original reporting fixture, fixture explanation, and task-brief template. Figure references: SS03-01–03; D04.
Recording transcript
A good engineering brief makes success visible before an assistant starts work. It does not need special magic wording. It needs a clear goal, a known starting state, the information that affects the decision, and checks that tell us whether the result is acceptable. In this lesson we will transform a vague sensor request into a small reporting task.
The initial request says, fix my sensor, the output looks wrong, and clean things up too. You may know what that means because you have been looking at the project all morning. The assistant does not know which behavior is wrong, which files are current, or whether you are describing a compiler error, a software replay, or a physical observation. Clean things up also invites unrelated changes.
Begin by writing the goal separately from current behavior. Our goal is to make the explanatory report identify its inputs as synthetic. The current problem is that a reader can see a temperature and state without noticing where the values came from. That is a communication problem we can solve without replacing a sensor library or changing a warning threshold.
Next identify the starting state. Name the Chapter Three original reporting resources and the actual input file. This fixture has explicit validity flags; the different CP00 inspection log does not. Keep an unchanged copy. Later we will identify source versions using Git commits; for now, the named resource gives us a recoverable baseline. If you already edited it, provide the current relevant content rather than assuming the assistant sees the original.
Supply the context that could change the solution. For this task, the sample records, validity flags, state names, and origin requirement matter. A serial port does not, because no physical board is involved. For a different task such as cross-compilation, the operating system, shell, compiler, board core, and target options would matter. Context should be selected for the decision rather than collected indiscriminately.
Paths also need a root. Open reporting-input dot JSONL from the Chapter Three resources linked in the written lesson. Inspect its actual contents rather than substituting CP00's sample log. Do not refer vaguely to the log when several files have that name. A relative path becomes meaningful only in relation to a known folder, which the workbench lesson will teach you to verify.
Now write the constraints. Preserve sample values, validity, state names, and record order. Do not change firmware, timing, dependencies, or the fixture itself. These constraints keep the requested reporting improvement separate from other possible work. If the assistant believes an excluded change is necessary, it should explain that dependency before editing rather than surprise you with a much larger patch.
Choose the requested artifact. We will ask for a short plan and two illustrative revised report lines. That is different from asking an agent to modify files. The output should be small enough to inspect immediately. Once its meaning is correct, a later task can apply the selected change with an explicit file boundary and relevant checks.
Acceptance criteria describe what you will inspect. Both example lines must identify synthetic origin. Original temperatures and state labels must remain intact. Invalid input must remain invalid, and the answer must not claim a physical measurement. If no command ran, the response must not say tests passed. These criteria are observable, unlike a broad request to make the report robust or professional.
Include a negative case. A record can contain a temperature number and still be marked invalid. The report must not promote that number into a trustworthy reading merely because it is available. If the input origin is unknown, the assistant should preserve that unknown rather than invent a known source. Negative cases make the boundary of acceptable behavior easier to see.
Read the completed brief in the editor. It now names the goal, starting resource, input, current behavior, requested artifact, constraints, sources, and acceptance criteria. Notice how each part reduces a specific uncertainty. We have not made the request longer for its own sake. We have made the result easier to judge and the work easier to resume.
Submit the brief with the actual relevant input, or analyze the original reference response if service access is unavailable. Keep what came back. If the plan suggests a cloud dashboard, that idea is outside the task. If it renames WARN to ALARM, it violates the state-name constraint. A suggestion can be interesting and still be inappropriate for the current change.
Write a short review against each criterion. Accept the explicit origin label if it is correct. Reject changed values or state names with a reason. Identify whether commands actually ran. A useful review note might say that the label meets the goal, the state-name change must be removed, and all example lines remain illustrative. This leaves a concrete next action.
For your exercise, request a summary counting valid and invalid records in the actual sample log. Count the records independently first. Do not copy a count from an illustrative table elsewhere in the book. Name the original Chapter Three input, preserve it, and require the total and validity split to match your inspection. Save both the brief and your evaluation of the returned summary.
A brief can also specify when to ask a question. Ask for missing information when its answer would change the implementation or the meaning of acceptance. Do not require clarification for every minor wording choice. For this report, unknown recovery behavior may be irrelevant if you only preserve existing state labels, while an unknown input format is essential. This distinction keeps collaboration efficient: resolve consequential ambiguity and let routine choices proceed inside a clear boundary.
If the response expands into unrelated work, stop and return to the preserved baseline. Clarify the permitted output and restart with the smaller brief. Repeating be careful is less useful than naming the exact file and success condition. You are finished when another person could identify where to start, what to produce, and how to decide whether it is correct without reconstructing your entire conversation.
Download transcript
