I spent a long time writing deliberately vague task descriptions, and I could defend it. A complete brief took forty minutes. The teammate picking it up would skim it anyway, miss the one constraint that mattered, and message me a question I had already answered in paragraph three. So I wrote less and kept the rest in my head. Cheaper, given the reader.
Then the reader changed. Half the tickets on our board are now picked up by someone who immediately pastes them into Claude Code or Codex. And an agent is the opposite kind of reader: it will happily consume two thousand words of constraints, and it will not skim. Suddenly the forty-minute brief pays for itself.
Except the person supervising the run still does not want to read it.
One task, two readers
That is the actual problem, and it took me embarrassingly long to name it. A task in an agentic workflow has two participants with completely different needs:
- The agent needs the full context. Intended outcome, source material, constraints, edge cases, what evidence to produce at delivery, and the conditions under which it should stop and ask instead of guessing.
- The human needs a runbook. Why this matters, how to start the right session, which checks need human eyes, which decisions they are allowed to make alone, and where the agent must escalate.
Writing one document for both produces something that fails both. Trim it for the human and the agent hallucinates the missing constraints. Write it for the agent and the human skims, misses the escalation rule, and rubber-stamps a bad delivery.
What we actually write now
Every work item gets two blocks. Same task, same intended outcome, two audiences.
The agent block is long and boring on purpose:
Outcome: CSV export on the reports page matches the on-screen totals.
Source: apps/reports/, the export path is in exporters/csv.ts
Constraints:
- Do not change the on-screen aggregation. It is correct.
- Currency must stay in minor units end to end.
- Timezone for date bucketing is the workspace timezone, not UTC.
Edge cases: empty result set, >50k rows, refunds (negative amounts).
Evidence at delivery: a diff, the new tests, and one exported CSV
for the 50k-row fixture.
STOP and ask if: the on-screen totals themselves look wrong.
The human block is five lines:
Why: finance is reconciling by hand every month because of this.
Start: open the repo, run the agent against the task above.
You decide: whether the refund rows belong in the export at all.
Verify: open the CSV in Sheets, check one month against the UI.
Escalate: any change to the on-screen aggregation.
The second block is the one that gets read. That is the point.
The part I got wrong first
My first attempt at this was two separate tickets, one "for the AI" and one "for the human". That was worse than doing nothing. The two drifted within a week: someone updated the constraint in the agent ticket, nobody touched the human one, and the reviewer verified against a rule that no longer existed.
They have to be one work item with two sections, sharing one intended outcome and one definition of done. If you cannot express both from a single outcome statement, that is a signal the task is really two tasks.
Why "stop and ask" earns its place
The line I would keep if I could only keep one is STOP and ask if:. Agents are relentlessly agreeable. Handed an ambiguous task, they will pick an interpretation and build something coherent on top of it, and coherent-but-wrong is far more expensive to unwind than a question asked up front.
Naming the specific conditions under which the work should halt converts that failure mode into a five-minute conversation. It is the single highest-leverage line in the brief and it costs one sentence.
Verification is a human column, not a checkbox
The other thing worth being explicit about: which checks a person actually has to perform with their eyes. "Tests pass" is not verification when the agent wrote the tests. Naming one concrete manual check, open the file, compare one month, click the button, catches the class of failure where everything is internally consistent and collectively wrong.
We formalised this into a pattern we call the Dual Prompt, and there is a longer write-up with the reasoning and a fuller template here: https://wagglet.com/blog/dual-prompt-human-agent-task-design
If you want the mechanical version, a board where each item carries both blocks and the delivery loop enforces the evidence requirement, that is roughly what we built at Wagglet, and the workflow docs are at https://wagglet.com/docs/task-handoff.
Curious whether other people have landed on something similar. The failure mode I still have not solved is keeping the human block genuinely short as the task grows.
Top comments (0)