# Context and handoff guide

Haris Mekic · Mekreflect

This is the method I use to carry project decisions between Claude, Codex and a code workspace. It is a reusable guide prepared from my working practice, not a transcript or a promise that an agent will always follow it correctly.

## Start with the problem

Write down who needs the result, what is failing now and what a useful outcome looks like. Separate the business requirement from a suggested implementation. A request for more data may actually be a request for better relevance or a clearer decision.

## Select context

Give the agent the current requirement, the relevant implementation, the decision record and the acceptance checks. State which source takes precedence when an older plan conflicts with current code. Supply the smallest set that explains the task, not an indiscriminate archive dump.

Use these fields in a project brief.

```text
Purpose
User and current problem
Expected result
Current implementation
Sources to read
Decisions already made
Open questions
Allowed scope
Acceptance checks
```

## Assign the work

One agent investigates the current behavior. Another implements the agreed change. A reviewer checks the changed behavior against the brief. Give each a clear file or subsystem boundary when they share a workspace. Send findings between them; do not make the integrator the only place where context exists.

In my implementation, handoff records can also be generated by a PowerShell utility. The useful part is the contract, not the choice of shell.

```text
From agent
To agent
Task
Current branch and revision
Files changed
What was verified
What failed or remains uncertain
Risks
Next action
```

## Check a real failure case

Choose a case that should fail. Missing required source material should not become a confident proposal. An unknown transaction outcome should not trigger an automatic retry. A test result should state what it actually exercised.

Record the command, fixture scope, result and date. Distinguish a unit test with mocked providers from a live integration run.

## Retain the decision

Update the module blueprint with the change and its reason. Keep unfinished work visible. A new session should be able to answer what exists, what changed and what to do next without reconstructing the entire conversation.

## A worked example

This example is fictional and contains no client material.

An opportunity appears suitable but has no terms of reference. The investigator identifies where the draft generator gets its source text. The implementation task adds a document-sufficiency check at that boundary. The reviewer tests a complete assignment, a notice-only record and a failed document extraction. The handoff records each result and the unresolved extraction issue. The next agent receives those facts instead of a message saying the feature is done.

## Use with an AI assistant

This document describes a workflow. It grants no permission to read files, change systems, spend money or publish information. Apply the access and approval rules of your own project. Remove private client material before sharing a handoff outside its authorised team.