---
title: "Plan Before Acting"
description: "Write a plan with completion conditions, then follow a failed check through repair and recheck. Compare the checklist's status with the actual tool results."
source: https://vizlearn.app/ai/agents/todo-write
access: premium (interactive player requires Lifetime; this doc is free)
---

# Plan Before Acting

Plan Before Acting means writing down the work and its completion conditions before running tools. An agent's checklist records intention and progress; tool results establish what happened. Keeping those two records aligned makes unfinished work visible, especially when a failed check requires a repair and a revised plan.

Treat the plan like a work order. Writing "repair the cleaner" on it does not repair anything. Checking that line off does not repair anything either. The useful part is the connection between the instruction, the work performed, and the evidence that lets you close it.

## How Plan Before Acting Works

A useful plan names an observable outcome for each item. "Handle the names" is hard to verify. "Run both selected examples against the current cleaner and compare the outputs" gives you a completion condition you can check.

This walkthrough uses three task statuses: `pending`, `in_progress`, and `completed`. Selecting a task moves it into progress. A tool then changes an artifact or returns a check result. Updating the plan is a separate action. In particular, a failed check is an observation; it does not automatically fix the artifact or create a repair task.

The **Evidence first** rule consults the completion condition before marking a task completed. If verification fails, this teaching harness inserts a known repair, does that work, and returns to verification. **Check off attempts** marks a task completed after its tool attempt, even when the check failed. It leaves the result visible so you can compare the status with the evidence.

These are explicit harness policies. A todo status field does not itself enforce either one. The distinction taught in [Tool Calling](https://vizlearn.app/ai/agents/tool-calling) still applies: the component that executes the tool produces its effects. A progress update only describes the work.

## Plan Before Acting Step by Step

The default is **Evidence first** with **Include inner space** selected. The goal is to remove spaces around names, preserve spaces within them, and add a usage example. Both the cleaner artifact and the usage artifact start absent.

### Write completion conditions

The initial plan contains three pending tasks:

| Task | Work | Done when |
|---|---|---|
| t1 | Write the name cleaner | The cleaner is saved |
| t2 | Check the examples | Both selected checks pass on the current revision |
| t3 | Add a usage example | The usage example is saved |

No tool has run. Neither artifact exists. Saving the cleaner and proving its behavior are separate items, so completing t1 will not certify that the implementation is correct.

### Execute the draft, then update the plan

The harness activates t1 and saves revision 1 of an authored draft that removes every ASCII space. At the write beat, the cleaner exists and t1 is still `in_progress`. The next result identifies the saved revision. Only the following plan update marks t1 completed.

Now t2 becomes active. The harness runs the two selected checks against revision 1:

| Input | Expected | Actual | Result |
|---|---|---|---|
| `" Ada "` | `"Ada"` | `"Ada"` | Pass |
| `" Ada Lovelace "` | `"Ada Lovelace"` | `"AdaLovelace"` | Fail |

The first example exercises removal of surrounding spaces. The second also requires preservation of an interior space. Removing every space satisfies the first example and breaks the second. The player displays spaces as dots to make that missing character visible; the actual strings still contain ordinary spaces.

### Revise after the failed observation

Verification remains unfinished. The evidence policy inserts t4, **Preserve inner spaces**, before t2 and returns t2 to pending. The plan is now t1, t4, t2, t3. Its counter changes from 1/3 to 1/4 marked completed because there is more known work. The completed t1 has not been lost.

Pause at this point: the plan includes a repair, but the cleaner is still revision 1 and still removes the interior space. That separation is the reason to keep the checklist and the workbench visible together.

The harness activates t4 and saves revision 2, whose authored repair removes only leading and trailing ASCII spaces. The old check result belongs to revision 1, so it becomes **stale**. It remains useful history, but cannot certify the changed artifact. After the save result, t4 is marked completed.

### Recheck and close the remaining work

The harness activates t2 again and runs fresh checks against revision 2. This time the outputs are `"Ada"` and `"Ada Lovelace"`; both selected examples pass. Verification can now be marked completed with evidence from that revision.

Finally, t3 saves the usage example `" Ada " -> "Ada"` and is marked completed in a separate update. The audit reports **4/4 tasks marked completed and 2/2 checks passed**. The default run has made five tool calls: the draft write, the first check run, the repair write, the second check run, and the usage write.

## What a Completed Checklist Proves

Choose **All checked, still wrong**. The recipe pauses before verification, with the same draft and inner-space inputs. After the failing result, the attempt policy marks t2 completed and continues to the usage task. It inserts no repair and makes no second check call.

The final checklist reads **3/3 marked completed**, while the latest checks read **1/2 passed**. The actual boundary output is still `"AdaLovelace"`. The audit only reads these records; it does not quietly repair the discrepancy.

You can also select **The easy examples pass**. Its inputs are `" Ada "` and `" Grace "`. The draft passes both, so either policy ends with three completed items and two passing checks. This is a limit on the evidence: those examples do not test the interior-space requirement. Passing them says nothing about a name they omitted.

There is no completion-rate measurement here. Comparing these deterministic policies explains what a progress record establishes, not how often a language model will succeed with or without a written plan. The [Claude Agent SDK todo guide](https://code.claude.com/docs/en/agent-sdk/todo-tracking) documents structured status updates and also models that track multi-step work without a written todo list by default.

## Edge Cases

- **The plan grows after a failure.** A denominator changing from three to four tasks can mean that new work was discovered. Keep stable task IDs so the completed history remains recognizable.
- **An artifact changes after verification.** Results apply to the revision that was checked. A repair needs a fresh check even if its name sounds correct.
- **All selected checks pass.** Coverage still matters. The plain-name examples miss the exact behavior that the inner-space example exposes.
- **A task is too broad.** Separate writing an artifact from verifying it when they require different evidence. Otherwise, "completed" can conceal which part happened.

## Common Mistakes

- **Treating a planned action as an executed one.** Inspect the artifact or result. A new checklist row has no tool effects.
- **Marking verification complete because a test command returned.** Inspect its result; a completed invocation can report a failing check.
- **Reusing stale evidence.** Match each check run to the artifact revision it tested.
- **Treating a written plan as a success guarantee.** Plans expose commitments and progress; their value depends on how they are used and what the checks cover.

For work spread across restarts or dependencies, continue to [Task System](https://vizlearn.app/ai/agents/task-system). Its task graph and persistence address different problems from keeping one local checklist aligned with results.

## What To Try

Start with **Before the first tool**. Predict which artifact changes when the plan is written, then advance to the write and completion beats. Compare **Repair after a failed check** with **All checked, still wrong**: keep the inner-space example and change only the completion rule. Finally, use **The easy examples pass** to test whether passing checks necessarily cover the full goal.

## A Note on Simplification

This is an explainer, not a substitute for formal training in agent design or software verification. The tasks, initial draft, and repair are authored fixtures; no model generated or discovered them. The browser executes the string transforms and checks in memory. The harness permits one active task, one known repair, and two selected examples using ASCII spaces. It omits model planning, tool failures, concurrent work, persistence, and unrestricted inputs. Passing these checks is not a proof of correctness for every name.