“Make this workflow faster” gives a capable agent plenty to do, but says little about which behaviour must survive, who consumes the result, or what would count as an improvement. A reviewer who receives those questions only after the code arrives has to reconstruct the assignment.
Assay organizes software work carried out by coding agents into streams and briefs. A stream holds a coherent body of work: its purpose, approved direction, decisions and dependencies. A brief is one bounded work request within it, small enough to implement and review as a distinct change.
This series, How the review system works, follows the path from an idea to accepted work. The following articles examine authoring, agent review, deterministic checks, independent verification, operational learning and measurement in turn.
Give the work boundaries
Our running case comes from the Desk tools stream, which develops the commands Assay agents use to coordinate and deliver work. One of those commands, deskpost, posts a review under the reviewer’s identity and checks the conditions for doing so. Before it acts, shared safeguards consult an audit ledger: a history of previous tool activity.
As that history grew, reading it became expensive. The performance work started with a simple question: why read the entire ledger when a safeguard needs only its final entry? The harder question followed immediately: which other decisions really do need older history?
Within the existing stream, the work was divided into separate briefs. Brief 23 added local usage and timing records. Brief 24 changed how the audit ledger was read and rotated. Brief 25 reduced repeated credential lookups. Each had its own deliverables and acceptance checks. We will follow Desk tools brief 24 through this series.
The split follows dependencies and independently reviewable outcomes. Different directories alone do not make work independent: two changes may still disagree over one shared meaning or resource.
A brief carries its reason, scope, deliverables, risks and verification expectations. In this case, the author traced the readers of the ledger: the stop switch, write budgets, repeated-failure protection, duplicate-post prevention and recovery tools. Making a read faster had to preserve the decisions those consumers made.
Review starts when the work request is written.
The brief’s acceptance contract required the bounded reader to return the same write-budget and failure-protection decisions as the full reader. Rotating the ledger into daily files had to preserve the history used to prevent duplicate posts. Tests would compare both readers against the same deliberately difficult histories.
Those conditions gave the worker an implementation target and gave the reviewer something concrete to challenge. The brief specification defines the fields that carry that contract.
Review the obligation and the change
A worker implements a brief on its own branch and opens a draft pull request. The review agent examines the candidate against the brief, applicable decisions and affected system context. It can request changes; the worker answers findings with repairs or evidence, and the changed candidate returns for review.
The intended division has four questions:
- Correctness: Does the behaviour meet its requirements, including failure and recovery?
- Security: Does the change preserve authorization, trust boundaries and control of data?
- Performance*: Can the required result be achieved with less repeated work, contention or resource cost?
- Architecture*: Does the change preserve clear ownership and move toward the approved design?
*Performance and architecture reviews are planned.
Each question reveals a different consequence. A faster ledger reader can miss an old refusal and accidentally permit a write. Rotation can preserve the newest record while hiding a previous post. A second history index can introduce another owner whose answer drifts from the ledger.
The reviewer groups observations about the same underlying defect into one finding, with the relevant evidence attached. Performance and architecture assessments* also bring costly algorithm and ownership decisions into planning, before implementation commits the team to an approach.
Turn obligations into executable checks
For the ledger change, CI compares the write decisions made by the full and optimized readers on the same histories. One history contains five consecutive refusals spread over several days, the latest one minute ago. The retry pause lasts until 15 minutes after the latest refusal, so it must still refuse the next attempt. After that pause, the breaker permits a fresh attempt. An hour-only reader sees too little history and gets that decision wrong.
In this worked example, the worker repairs the stopping rule and supplies the comparison. Mutation testing then deliberately reintroduces the hour-only shortcut and asks whether the tests notice. A green execution is useful because the required decision and the wrong answer are both explicit.
The CI article works through that experiment, then explains how publication checks, quality history and ratchets apply the same discipline to other obligations.
Verify after merge
In the ordinary flow described here, the review desk makes a draft ready only after the applicable current-candidate reviews and checks are satisfied. A human merges. A separate verifier then runs the brief’s verification checks against merged main.
That separation answers two different questions. Review judges the candidate and its obligations. Verification checks the resulting integrated state and records what happened. The implementer’s own successful run is useful evidence during development; it does not supply the independent verification step.
A failed check stays visible. So does a check that could not run. The verifier records results and limitations, and discovered defects return to the appropriate work owner. The lifecycle distinguishes implemented, verified and done because merging alone cannot answer all three.
Use evidence to unblock dependent work
Suppose a later brief adds a report command that consumes the ledger’s rotated files. Its worker needs the segment-reading behavior to be independently checked. Merging that implementation records progress; verification supplies the evidence an ordinary build dependency requires.
The report brief can become eligible when its prerequisite reaches verified or done. If a separate release gate requires an owner’s sign-off, that decision remains outstanding until the named acceptance occurs. The dependency states what evidence the next action needs.
Keep learning after delivery
A faster shared safeguard can still leave a reviewer waiting on the rest of deskpost. The audit-ledger brief deliberately retained one full-history read in the posting path because duplicate-post prevention relied on it. That remaining work gives a later assessment a concrete place to look.
The continuing-operations model* follows those questions beyond the delivery stream. It links a user goal to the workflow supporting it, records what a change expects to improve, and assigns a later assessment after exposure. Performance reviews* would examine accumulated cost; architecture reviews* would examine drift and temporary mechanisms that outlived their purpose.
The review method also improves: better specification coverage, reviewer context and validation of findings can be compared with the existing procedure. The continuing-improvement article follows that learning alongside user-journey assessment.
A confirmed problem would return as a bounded brief, pass through implementation, review and verification, and then be assessed in use. That is the intended self-healing connection: observations lead to another checked improvement.
Measurement follows the work through arrivals, implementation, review, repair and verification, then through its use. For our ledger case, the measurements include bytes read, time spent in the safeguard, time for the complete posting command and the effect on a reviewer’s workflow. The measurement article follows those different clocks.
An engineering lead can borrow the structure without adopting every tool. Before assigning work, name what must change, what must survive, what evidence would reject a plausible wrong result, and who checks it independently. Those decisions give the review agent something specific to defend.
*Continuing operations and its recurring assessments are planned.