A Task Log for Agent Work: What Was Asked and What Shipped

Most teams that try a task log over-collect on day one and stop writing entries by day three. Keep the schema small enough that writing an entry takes under a minute, and detailed enough that a stranger (or an agent) can reconstruct the decision.

Two fields are easy to omit and expensive to omit. The first is the verbatim prompt: the difference between a prompt that produced an accepted diff and one that produced a rejected diff is often a single missing constraint, and you can only see that if both are recorded. The second is the review reasoning. A bare rejected tag tells the next session nothing; rejected: retried on 429 but not on 500, spec says retry all 5xx tells it everything.

Treat the prompt as a versioned artifact rather than a throwaway. Prompt and agent-description quality is a known source of routing and behavior errors, and precise descriptions of what a tool or agent does, with inputs and outputs spelled out, reduce them per Oracle's agent prompt guidance. Your log is where that precision accumulates.

The storage decision mostly answers one question: can both the human and the agent read and write it with the tools they already have? Agents can read files, run shell commands and call HTTP endpoints. People read rendered Markdown and diffs. Choose the overlap.

Version-controlled Markdown in the repo. One file per task under something like docs/tasks/, with the prompt in a fenced block and the diff referenced by commit SHA. Agents can read it with a file tool, humans get it in the PR, and it is reviewable. This is the best default for code work.

An append-only JSONL file. One JSON object per line, one line per task. Good when you want to script over the log: compute acceptance rate per prompt template, or select the last five entries automatically. Agents parse it trivially.

A database or issue tracker. Best when multiple people and multiple agents share the log across machines. The cost is that agents need a tool to query it, so you must give them one.

The chat transcript. Worst option. Transcripts are long, unstructured, and invite the goal-drift pattern described earlier. Keep transcripts as raw material; never use them as the handoff artifact.

A workable hybrid: a small index file at a fixed path that agents always read first, plus per-task entries. The index carries the last few tasks and a pointer to the full history.

{"task_id":"AUTH-142","requested":"Reject expired reset tokens","spec_ref":"docs/specs/auth-reset.md","prompt":"See docs/tasks/AUTH-142-prompt.md","artifact":"commit 3f9a2c1","review":"accepted-with-edits","evidence":"pytest tests/auth -q: 41 passed","next":"Add rate limit on reset endpoint"}
{"task_id":"AUTH-143","requested":"Rate limit reset endpoint","spec_ref":"docs/specs/auth-reset.md","prompt":"See docs/tasks/AUTH-143-prompt.md","artifact":"commit 8b1d4e0","review":"rejected","evidence":"pytest tests/auth -q: 3 failed (token bucket off-by-one)","next":"Fix bucket refill math, re-run"}

One practical note on prompts: store them in files and reference them from the log line. Fenced blocks inside JSON are painful to diff and review. The JSONL entry stays small, and the prompt file is what you actually edit and compare across tasks.

A log written from memory at the end of the day drifts toward success stories. The reliable pattern is to create the entry before the agent runs, then fill in the outcome.

1. Create the task ID and write requested, spec_ref, and the prompt file before you send anything.
2. Send the prompt exactly as written. If you improvise extra instructions in the chat box, update the prompt file and note the edit, otherwise the log lies about what the agent saw.
3. When the diff comes back, record the artifact reference (commit SHA or file path) and run the evidence command.
4. Record the review outcome with one line of reasoning, and the next slice.
5. Commit the entry in the same pull request as the code, or immediately after a rejection.

Step 5 matters more than it looks. Reviewing AI-generated code works best when reviewers treat diffs as drafts and check them against the original intent, which requires the intent to be written down somewhere alongside the diff. A benchmark dataset cited in that review found that AI-assisted pull requests are notably larger than unassisted ones and have a far lower 30-day acceptance rate, which is precisely the pattern that a log of rejected tasks helps you diagnose.

For multi-step work, write the log at the granularity of the slice, not the epic. Splitting work into small vertical slices is a long-standing practice in story splitting, and the same logic applies to agent tasks: a slice is small enough to review in one sitting and to describe in one log entry per the Humanizing Work guide. If an entry needs three paragraphs of context to make sense, the task was too big.

The loading step is where the log pays for itself. Do it before the agent touches anything, and keep it to the last three to five entries plus the spec reference.

A simple, portable opener:

Read docs/tasks/index.jsonl and docs/specs/<feature>.md before doing anything.

From the log, summarize in at most 10 lines:
1. What is already shipped for this feature (task IDs and commits).
2. What was rejected and why.
3. Open constraints discovered along the way.
Do not restate the full caveats. Wait for my next instruction.

Three details make this work. First, it forces a summarization step before action, which is the same idea as context folding, where a sub-trajectory is collapsed into a concise summary of the outcome while preserving progress as described in the Context Folding work. Second, it scopes the read: the agent reads the log and the spec, not the whole repository and every past transcript. Third, it asks for the rejected tasks by name, because that is the information a fresh session never has and most needs.

For debugging, a structured entry with the prompt and evidence makes a natural trace record. Agent observability tooling built on OpenTelemetry conventions captures tool calls, tokens and costs, and open-source tools visualize those traces for agents in production. A task log is the human-readable companion to that: the trace tells you what the agent did in one run, the log tells you what was decided across runs.

If you are running many agents on one codebase, the same opener works with one change: add "read only entries whose spec_ref matches this area." That keeps each agent's context small and relevant, which is the whole point.

A handoff is the log's hardest test. The incoming person may be a colleague, a contractor, or a different agent with a different harness. They all need the same thing: what was asked, what shipped, what failed and why.

Before handing off, do four things:

• Update the index file with a one-line status per open task.
• Make sure every accepted task has an artifact reference that resolves (commit SHA exists, tests are green on that commit).
• Make sure every rejected task has a reasoning line that states the constraint discovered, not just the verdict.
• Add a known-issues section to the spec with anything the log revealed but did not fix.

For the incoming side, the opening prompt is the same as above, plus one line: "List any open questions that the log does not answer, before suggesting work." That line surfaces gaps cheaply. If the log cannot answer "does the retry logic apply to 4xx," the incoming session asks rather than guesses, and the answer goes into the log.

If your handoffs cross model providers, keep the log format provider-neutral. Plain JSONL with no model-specific fields in required positions means the same entry feeds an agent on any harness, which is the practical argument for keeping the exact prompt in a file rather than buried in a tool-specific session store. If your work spans several providers, putting them behind a single OpenAI-compatible endpoint with one key, as Quanta Inference does, keeps the log's model and cost fields consistent across tasks and makes the acceptance-rate comparison fair.

The log turns into something more useful than a record once you have 20 or 30 entries: a dataset about your own agent workflow.

Three queries are worth running by hand or with a small script:

Acceptance rate by prompt template. Group entries by which prompt file or template they used and count accepted plus accepted-with-edits against the total. A template with a low rate is usually missing a constraint that appears in the reasoning of its rejections.

Edits per accepted diff. If most accepted work needed edits, your specs are underspecified, not your agent. The spec-first literature is consistent on this: alignment work done before implementation reduces downstream rework according to Microsoft's practical lessons.

Rejection reasons clustered by type. Sort the reasoning lines into buckets like scope, correctness, missing constraint and test failure. The largest bucket names the fix.

The decisive signal is the shape of the work rather than the count. If rejections cluster around scope (the agent changed files beyond the task), tighten the spec's boundary section. If they cluster around correctness on multi-file edits, the task is too large for one slice and needs splitting. Structure is what makes agent work predictable; JetBrains' spec-driven guide argues the same thing with a requirements, plan and task-list sequence written to files that survive the conversation step by step. The task log is the fourth file in that sequence: the record of what actually happened when the plan met the code.