Trace the Work

The Problem This Solves

A code diff shows what changed. It rarely shows why the agent made that change, which files it inspected, which tests shaped the decision, or which constraints were active in the session.

That missing trail becomes a context problem later. The next agent revisits the code and has to rediscover the same evidence from scratch. Worse, it may undo a decision because the rationale lived only in a chat transcript that never traveled with the repository.

Git stores the artifact, and agent work also needs provenance when the reasoning trail matters for maintenance.

How It Works

Persist a trace of the work next to the artifact or in a retrievable project store. The trace should be structured enough for future agents to use without replaying the whole conversation.

A useful trace captures:

Field	Purpose
Changed files and line ranges	Shows the exact artifact surface
Read files and line ranges	Shows the evidence considered
User request	Preserves the original goal
Key decisions	Records why the change took this shape
Tests or checks	Shows what was verified
Model and tool session	Gives audit and debugging context

Agent Trace is an open specification for this kind of record. It tracks files, line ranges, conversations, model identifiers, related resources, and VCS revisions. The important part for context engineering is that the trace becomes future context, ready to retrieve when another agent touches the same code.

Example

An agent changes a payment retry policy. The diff only shows a retry count moving from 3 to 5 and a test update.

A trace adds the missing context:

goal: Reduce false payment failures during provider brownouts
changed:
  - payments/retry_policy.ts:18-44
  - payments/retry_policy.test.ts:72-118
read:
  - incidents/2026-05-provider-brownout.md:1-80
  - docs/payments/retry-contract.md:10-36
decisions:
  - Keep exponential backoff cap at 90 seconds
  - Do not retry card_declined responses
verified:
  - npm test -- payments/retry_policy.test.ts

A future agent can now see that the retry increase was scoped to provider brownouts, with ordinary payment failures left under the existing policy.

When to Use

• Codebases where agents repeatedly modify the same areas
• Regulated or high-risk systems where provenance matters
• Long-running projects with multiple agent sessions, humans, and branches
• Changes where the reasoning depends on external evidence, incidents, specs, or tickets

When Not to Use

• Tiny throwaway changes where the commit message contains enough context
• Private experiments that will never be maintained
• Traces that store sensitive conversation data without access control or retention rules

Related Patterns

• Write Outside the Window persists context so it can survive beyond one session
• Context Handoff is stronger when the handoff includes traceable evidence
• Scratchpad captures working state during the task; this pattern keeps the final provenance
• Retrieval Subagent can use traces as high-signal retrieval targets