A coding agent can follow a request faithfully and still deliver the wrong result. “Make this read faster” says nothing about the decisions that depend on the data being read.
In Assay, a brief is a bounded work request: the outcome, scope, constraints and acceptance evidence an implementer and reviewer share. Related briefs belong to a stream, which gives the work its purpose and direction. Writing the brief includes deciding what successful work must preserve.
Start with the answer the user needs
Desk tools brief 24 tackles growing audit-ledger reads. One consumer is deskpost, the command that posts an agent’s review. Before posting, shared safeguards consult recorded activity to enforce write limits and stop repeated unsuccessful attempts.
The first opportunity looked simple: the common guard parsed the whole ledger to inspect its final entry. But other readers ask different questions. A budget counts activity within an hour. A failure breaker counts consecutive refusals beyond that budget window. Duplicate-post prevention searches for an earlier successful post of the same review revision.
Those questions require different amounts of history. The request became “make each read proportional to the answer it needs.” The last-entry lookup can stop almost immediately. The budget reader must establish both the time-window count and the failure run. Deskpost’s duplicate-prevention lookup keeps its full-history read in this brief.
The stream split the work by mechanism: brief 23 adds usage and timing records, brief 24 changes ledger reads and rotation, and brief 25 reduces repeated credential lookups. Each has an outcome that a worker can implement and another party can check.
Test a plausible shortcut
Here is the rule that makes the ledger example interesting: five consecutive in-scope refusals trip the failure breaker. Its pause lasts until 15 minutes after the latest refusal, then permits a fresh attempt. Older members of the run still count; the latest timestamp determines whether the pause applies. A successful progress entry resets the run. Results such as a dry run are ignored: they neither increment nor reset it. The run is separate from the one-hour budget window.
Consider five refusals for the same tool and target, with no intervening progress:
4 days ago refused
3 days ago refused
2 days ago refused
1 day ago refused
1 minute ago refused
Now another write is requested
The full history says to refuse: the run has reached five. A reader that stops at one hour sees only one refusal and would miss that protection. The time window is a valid boundary for one question and an invalid boundary for another.
The reader can stop only once the budget window is covered and both failure runs are determined: the run for this tool and target, and the backstop run across all targets for this tool. The tool-wide backstop trips after twenty consecutive non-progress attempts across all targets, including a run on just one target.
It uses the same 15-minute pause from the latest attempt; successful progress resets its run and neutral results are ignored. If its resource cap arrives first, it discards the partial answer and uses the full reader. That fallback is part of the requirement.
Change the input by putting a successful progress entry after the old refusals. That resets the run. A useful test must exercise that case too; otherwise a worker could “fix” the first example by refusing every request.
Trace the affected consumers
A brief names where it acts, who consumes the changed representation and which behavior remains authoritative. The ledger’s guard, budget reader and recovery command needed updates. Every reader had to traverse the daily files introduced by rotation. Duplicate-post prevention retained its existing full-history behavior.
For rotation, the important boundary is logical history, rather than the current filename. Moving yesterday’s records into a segment must preserve the same write decision and the same remembered post. Recovery must still quarantine a malformed line while retaining the good records across those segments.
Earlier fixes and files that frequently change together help the author find less obvious consumers. The CI article explains how quality-history tools support that investigation. The brief still needs to record the actual dependency it discovers.
Make the acceptance check executable
The definition of done describes the delivered result. A Verify row tells another party how to examine it, including the input and expected behavior.
The author decides what good work must preserve before asking an agent to produce it.
The ledger brief’s central comparison check runs:
cd tools/desk
go test ./internal/deskkit/ -run '^TestBoundedPointsForMatchesFullParseVerdicts$' -count=1
Its fixture includes the old-refusal history, reset events and ignored results. It asks both readers for the write decision on the same input and compares their answers. The expected result is the same allow-or-refuse answer from each separate budget and failure check, whether it applies to one target, a repository or the tool as a whole. Changing the optimized reader to stop at the time window must make this test fail.
That is stronger than “test the reader” or “compare row counts.” Equal row counts can still produce different permission decisions. The observable belongs to the preserved requirement.
Performance receives its own criterion: on a planted ledger of at least 100 MB, the guard’s median over 20 runs must stay below 50 milliseconds. The test also prints the old reader’s median for comparison. A separate test checks that the last-entry read remains bounded as history grows. Together they say what faster means and what must stay true while achieving it.
Let risk determine acceptance
Assay’s brief format asks about regulatory, customer, irreversible and sensitive-data risk. Any yes requires a human acceptance gate; four no answers select a model gate, where an independent model review supplies the acceptance judgment. The ledger brief answers no to all four questions and uses that model gate. Its reasoning is explicit: decision-equivalence tests, fallback controls, rotation tests and fault planting bound the hazards within this code change.
The human still owns the ordinary merge decision. A human acceptance gate is an additional decision required by a brief’s risk and scope; it is distinct from merging every candidate. A request author needs to say what that additional owner will decide when it applies.
Acceptance quality also deserves review. The proposed specification-review refinement asks whether material conditions have observable outcomes and whether changed requirements still agree with inherited decisions. A populated template gives that examination a starting point.
The reviewer can challenge the classification as well as the code. Splitting consequential work into smaller briefs does not remove the underlying risk.
Verify the prerequisite
A dependency belongs in a brief because the worker needs an earlier result. Sharing a stream or touching nearby code is insufficient.
brief 24 has an empty prerequisite list. Suppressing successful credential-cache reuse rows initially looked as though it might require the usage telemetry in brief 23. The author checked: safeguards did not consume those rows, and replacement observability was optional for this change’s acceptance. The telemetry therefore remained separate work.
This is where to challenge an assumed first blocker. An unnecessary prerequisite delays every item behind it. When a dependency is real, name the interface or verified behavior it supplies. The verification article follows a positive dependency through readiness.
Give the reviewer a contract
The worker can choose an implementation that meets the contract. The reviewer checks both the chosen solution and whether the request omitted a consequential obligation.
For this case, permitting a write after the five-refusal history is a contract violation. Keeping an extra authoritative store for remembered posts raises a design question about synchronization and recovery. Those are different kinds of objection, and the brief gives each a basis.
Give the request to someone outside the author conversation. They should be able to explain the outcome, the affected consumers, one plausible wrong result and the check that would reject it. Missing answers belong in the brief before implementation starts.