Driving a Session: Plan, Steer, Restart

Why this matters

CR-111 is the async/await refactor: move src/orders/ from callback style to async/await without changing behavior. Omar types the whole request into Quill in one message and lets it run. Forty minutes later Quill has touched 31 files. Half the tests are red. Every correction Omar types makes the diff bigger, and Quill has started rewriting public function signatures he never asked it to touch. Jun walks over, presses Esc, and closes the session. He opens a fresh one in plan mode, has Quill write a plan, splits the plan into four steps, and runs each step in its own session with make test green at the end. The refactor is merged by lunch. Same agent, same codebase, same request. The difference was how the session was driven.

1. Task sizing

A session is one conversation with the agent, from the first message until you clear it or close it. Task sizing is the habit of shaping a task so that one session can finish it. A well-sized task has three properties. It has a definition of done, a sentence that says what must be true when the work is finished. It touches a handful of files. And it can be verified with one command.

Signs that a task is too big:

• You cannot name the files it will touch.
• The definition of done contains the word "and" more than once.
• There is no single command that proves it worked.
• You expect the session to run longer than thirty minutes.
• You would not hand it to a new hire on their first morning without breaking it up.

2. Plan before build

Plan mode is a Claude Code mode in which the agent can read and search the repository but cannot edit files or run commands that change anything. Press Shift+Tab to cycle the permission mode until it reads plan. In plan mode you ask for a plan, not for code. The agent reads what it needs and proposes steps. You edit the steps, approve, and the session leaves plan mode.

A good plan holds four things: the steps in order, the files each step touches, the command that verifies each step, and what the plan will not touch. That last item is the one most plans miss, and it is the one that stops the agent wandering.

Omar makes two edits before he approves. First, he extends the last line: keep the public API, meaning the exported function signatures, not only their names. Callers in src/giftcards/ depend on them. Second, he moves src/orders/create.ts to step one, because it has the most callers and the best test coverage. If that conversion goes wrong, he wants to know first.

The plan is a document you own. Editing it is the cheapest steering you will ever do, because nothing has been built yet.

3. Splitting

One plan, several sessions. Each step in the plan becomes its own session with its own done check. The session for step 2 starts with a clean context, reads plan.md, does step 2, and ends when make test is green and the diff is committed. The next session starts from that commit.

Why not all four steps in one session? Because every file read and every test run stays in the context. By step 4 the agent is carrying the whole history of steps 1 to 3, including the wrong turns. A fresh session carries the plan and the current code, nothing else.

4. Watch the first three actions

The first reads and the first edit tell you whether the agent understood the task. If Quill's first action on step 1 is to read src/orders/create.ts, good. If its first action is to read src/giftcards/refund.ts, it has misread the boundary, and you should say so now, not after it has edited that file.

To steer is to correct the agent mid-session with a short, specific message. One sentence. Name the action to stop and the action to take instead. A paragraph of explanation goes into the context and competes with the brief; a sentence lands.

In the first, failed session, Omar typed three paragraphs about why the public API mattered and asked Quill to "be careful." Quill agreed and kept changing signatures. Careful is not an instruction. "Only the bodies" is.

5. Steer or restart

A correction works when the agent changes course and stays on it. A correction has failed when you find yourself typing the same thing a second time. The third time, you are not steering; you are arguing with a session that has drifted. Drift is the gradual loss of your constraints as the context fills with other material.

To restart is to end the session, add the lesson to the brief or the task message, and begin again with a clean context. A restart feels like losing work. It is usually the fastest route, because the new session starts with the constraint in front of it instead of under forty turns of history.

Restart when:

• You have corrected the same thing twice.
• The agent says it will do one thing and does another.
• The diff is growing and the tests are not getting greener.
• You can no longer say what the session has and has not changed.

6. Context hygiene

Context hygiene is the set of habits that keep the agent's working memory clean: clear between tasks, compact when a long session must continue, and never carry an unrelated task into a session. When Omar asks Quill to fix a checkout email typo "while you are here" in the middle of step 2, the email files, their tests, and the email boundary all land in the context, and the CR-111 diff grows an email change Jun has to review. A stray task gets a note and its own session later.

/clear starts a fresh context. Use it at the boundary between tasks, every time. /compact summarizes the session so far into a shorter form and frees space. Use it when a long session must continue and you can see it slowing or forgetting. Compaction is a summary written by the model, and a summary loses things. It keeps what looks important and drops what looks incidental, and it has no way of knowing that the sentence you typed at turn 3 was the whole point.

The fix is not to avoid compaction. The fix is to put constraints where compaction cannot lose them: in plan.md, in the task message that opens each session, or in CLAUDE.md if the rule holds for every task. A file is read again. A turn is summarized away.

7. Verify first, trust second

Verify first is the habit of asking for the failing test or the reproduction before the fix. The agent writes a test that describes the wanted behavior, runs it, and shows you the failure. Then it writes the code. The failing run proves the test tests something, and the passing run afterwards proves the code did it. This is the same move as the failing test in Spec-Driven Development for Dummies, L3, applied inside a session.

Without it, you get the L0 story again: green tests and a deleted assertion.

8. Parallel sessions

Two sessions in one checkout is a race. Session A edits src/inventory/list.ts; session B runs make test, sees A's half-finished edit fail, and "fixes" it. Neither session knows the other exists. A worktree solves this. A git worktree is a second working directory attached to the same repository, on its own branch, with its own files on disk.

# From the Shelf checkout: a second working tree on a new branch.
git worktree add ../shelf-cr112 -b cr-112

# In a second terminal, start a separate Quill session there.
cd ../shelf-cr112
claude

Now each session has its own files, its own branch, and its own test runs. Parallel sessions are safe when each one has a worktree of its own. This is plain git; no agent flag is needed.

Summary

• Size the task first: a definition of done, a handful of files, one verifying command. CR-110 is one session; CR-111 is a plan and four.
• Plan before build: in plan mode the agent reads and proposes but cannot edit. Edit the plan, add what it must not touch, then approve.
• Watch the first three actions and steer with one specific sentence. If you correct the same thing twice, restart with the lesson written into the task message or the brief.
• Keep context clean: /clear between tasks, /compact only within a task that must continue, and constraints in files that compaction cannot lose.
• Ask for the failing test before the fix, and give every parallel session its own worktree.