precap

/precap — the recap written before the work

A precap is a recap from the future. You imagine the task is completely done, then write the account of the work it took and the end result, in past tense, as concretely as a real recap. Long-running agents lose the thread: context compacts, subtasks multiply, a detour starts to look like the task. A precap gives your future self a fixed reference to compare against. It does not predict the future; it records the imagined path, concretely enough that leaving it is detectable and revising it is explicit.

The difference between a precap and an educated guess is investigation. Every step in the path must point at something real in the repo, plan, or history. A step with no grounding is a hope.

Modes

• write (default): no precap.md for this task yet. Investigate, imagine, write, validate.
• check: a precap exists and work is under way. Compare reality against it and report.
• revise: reality diverged. Amend the precap without erasing what was imagined.

If precap.md already exists in the working directory and the user did not say which mode, read it first and default to check. Overwriting a live precap loses the drift history that makes it useful.

Phase 0 — Anchor the task

Establish what "done" means before imagining how it got done.

1. Capture the task statement verbatim: the user's words, the plan file, the issue, the PR description. It goes into the precap unedited so a later reader can see whether the interpretation drifted from the ask.
2. Read any plan that already exists: a plan-mode file, .cascade/<project>.md, a design or RDD doc, a Linear ticket. The precap sits downstream of the plan and must not contradict it silently. Where it does, say so.
3. Note the working directory, branch, and base. Run git status --short and git log --oneline -10. A dirty tree or a branch already carrying commits changes the story: part of the imagined path may already have happened.
4. Decide the scope questions that are the user's to make. If the task forks on something only they can settle (which API to keep, whether to migrate data, whether to touch a shared contract), use AskUserQuestion now with concrete options. Do not write a fork as decided when it is not. In Codex, use the equivalent structured user-input tool when available. When no user is reachable (a headless run, a cascade worker, a scheduled job), do not block: follow the branch that changes the least, write the fork with Decided by: the user (undecided), and add a Drift signal that fires if the run starts acting on the other branch.