Context and task handoff

Back to the Codex learning hub

Goal and preparation

Session resumption preserves conversation, which may not reflect current disk state. A handoff records goals, verified facts, unresolved issues and next steps for fresh validation. It is not a complete chat transcript or a file guaranteed to load automatically. Explicitly request it in the next task.

Step 1: Prepare a faulty copy and state marker

From the first-project ZIP, copy the five broken files into a new codex-handoff-lab. Unlike start, this fixture incorrectly returns unfinished tasks for Completed. Open the root in your editor and add LAB_STATE.txt below. Verify location with Get-Location in PowerShell or pwd on macOS/Linux, then run tests.

Lab: codex-handoff-lab
Revision: BROKEN-1

node --test core.test.mjs

Expect two passes and one filter failure. Mark this verified only after observing it. If Node is missing or the path is wrong, record the blocker and actual error summary instead of assumed counts. Do not store accounts, keys or full private tool output; fictional markers and relevant test evidence are enough.

Step 2: Write a verifiable handoff

Create handoff.md at the root. This complete example assumes the observed baseline above; correct Observed if your result differs. Goal defines the outcome, Scope allowed edits, Observed revision and commands, Not checked missing evidence and Next the first checks for the next session.

# Small Steps handoff

## Goal
Completed shows only completed tasks. Keep ordering, storage and existing UI.

## Scope
Lab: codex-handoff-lab. Only core.mjs may need a program change.
Do not change tests or add dependencies. Preserve other work.

## Observed
LAB_STATE.txt: Revision: BROKEN-1.
Command: node --test core.test.mjs
Result: 2 passed, 1 failed in the filter case.
The completed branch of visibleTasks currently selects unfinished tasks.

## Not checked
Browser interaction: NOT RUN.
Publishing and deployment: NOT PERFORMED.

## Next
1. Re-read LAB_STATE.txt, core.mjs and the test file; do not trust this record over current files.
2. Re-run the baseline before deciding whether a fix is still needed.
3. If still faulty, change only the completed predicate, then test and review the diff.
4. Manually check Read completed / Build active under all three filters.

## Stop condition
If revision, test results or files differ, report the mismatch and revise this record before editing program code.

“Made some changes” is not verifiable evidence. File names, behavior, executed commands and omitted checks let another person repeat the work. In a Git project, add branch and commit, but inspect uncommitted diff too: equal commits do not guarantee equal working trees. Do not invent a commit ID for this lab.

Step 3: Make the handoff stale and start fresh

Make a controlled change: copy only expected/core.mjs from the ZIP over this lab's core.mjs, change LAB_STATE.txt to Revision: FIXED-2 and leave handoff.md stale. Tests should now pass all three. This simulates another collaborator fixing the code after the recorded conversation. Other program files and tests remain unchanged.

Create a new desktop task for the same lab. In CLI, /exit to the shell, verify the directory and launch codex again without resume. Send the following request. Expect it to detect FIXED-2 versus recorded BROKEN-1 and three passing tests, then propose updating the record without modifying the already correct filter.

Continue this lab using handoff.md, but first verify it against current files. Read LAB_STATE.txt, core.mjs and core.test.mjs. Run node --test core.test.mjs. Do not edit anything yet.
Compare the recorded revision, predicate and test result with current evidence. Report mismatches and propose the smallest next step. Browser checks must remain NOT RUN unless actually performed.

If it still proposes fixing Completed, ask which current line is wrong and which test still fails. Current evidence must take priority over stale notes. Then authorize only handoff.md: update Observed to FIXED-2 and the actual three passes, and Next to the remaining browser checks. Briefly record that the original handoff was stale and revalidated.

Long conversations, compact and document roles

CLI /compact condenses long conversations while retaining important context. Enter it in the interactive composer, follow any confirmation and then compare its restated goal, constraints and remaining work with handoff.md. This lab need not artificially fill context. Compaction is not a file backup, Git rollback or guarantee that every detail survives. Preserve important decisions in readable files.

Check the handoff read-only after compaction

/compact

Use the command only in the original CLI task when compaction is needed, then send the request below. Do not pad the chat for practice. The answer should preserve the core.mjs-only program scope, unchanged tests and pending browser checks. Recover omitted constraints from files; never change FIXED-2 back to BROKEN-1 merely to match a summary.

After compaction, read handoff.md and LAB_STATE.txt from disk. Restate the goal, allowed changes, preserved files, actual recorded checks and remaining work. Compare the summary with the files and identify conflicts or missing constraints. Do not edit files or rerun tests in this check. Label recorded evidence separately from checks performed in this turn.

See rules and context files. Do not permanently place an entire incident log in AGENTS.md so every task inherits stale details. Put the present goal and last verification date near the top of the handoff, retain concise resolved outcomes, and remove or label invalid paths and temporary hypotheses.

Troubleshooting, restoration and acceptance

If the new task cannot find the file, check directory and name rather than searching the entire computer. If unread, provide its path and request the observed Revision. A test succeeding in another directory does not validate this code. If failure differs from the handoff, preserve both results and times, reread relevant files and decide before changing tests.

Completion requires an explanation of stale versus current state, updated handoff.md and evidence that core.mjs was not redundantly edited. To repeat, restore only broken/core.mjs, set LAB_STATE.txt to BROKEN-1 and restore the reference handoff. Diagram 1 records facts, 2 revalidates on handoff, 3 updates next steps. Model dialogue and /compact are documented procedures; record your own execution. The reference defect and fix have separate local tests.

Back to the Codex learning hub

Read the full description

Evidence to Handoff to Resume

• AI tools
• Tutorials
• Codex