Plan from Evidence

In plain words

Before a project starts, your team decides who waits for whom, otherwise two people build the same thing differently. A plan for an agent works the same way. Instead of a list like 'update API, add tests', you write small work items, each with facts from the code, what it waits on, and one command that proves it is done. Then the order falls out on its own.

How it flows

A tiny example

item = {
    "id": "W2",
    "change": "return balance in paise",
    "evidence": ["api/wallet.py:41 returns a float"],
    "deps": ["W1"],
    "proof": "python3 -m unittest tests.test_wallet",
}
if not item["evidence"] or not item["proof"]:
    reject(item)
for wave in group_by_dependencies(plan):
    run_together(wave)

Notice that evidence and proof are required fields, not comments, so a bad item gets rejected before any file is touched.

What you will learn

• Why a to-do list is not a plan, and what a real plan carries.
• How to attach evidence and proof to every piece of work.
• How to write ordering as dependencies instead of "first, then, after that".
• How to check a plan for cycles and missing facts before touching any file.

The problem, simply

Think about your final year project. Four of you sit in the hostel room and make a list on a rough page. "Build backend. Build frontend. Write report. Make PPT." Everyone nods. Everyone feels productive.

Then Rahul builds the login API returning a user id. Sneha builds the frontend expecting a full user object. Two weeks later they meet and both have to redo work. The list was not wrong. The list just did not say who waits for whom, or what "done" means.

The same thing happens when you hand a task to a coding agent. You say "update the API, add tests, update the docs." The agent happily does all three. But it never wrote down which file it looked at, why that file is the right one, which change must land first, or how anybody would know the change actually works.

See, the problem is that a list in future tense is just the request repeated back to you. It has no facts and no finish line. A plan has to hold facts.

The idea

A plan is a dependency graph. Each box in it is one small change, and each box carries five things.

The five things every work item carries

• Id — a short stable name like W1. Other items point at this name.
• Change — the smallest behaviour or contract change, one line.
• Evidence — actual facts from the codebase that justify it. A file path, an existing function, a failing test.
• Depends on — the ids that must be finished first.
• Proof — the exact command or check that closes this item.

IMPRemember: if an item has no evidence, you are guessing. If it has no proof, you will never know it is done.

Contract first, then everything else

When many parts of the code depend on the same behaviour, fix that behaviour first. That agreed behaviour is called the contract — basically the promise about what goes in and what comes out.

Suppose Priya is adding a "wallet balance" feature. Four things depend on it: the implementation, the tests, the docs, and the final integration check. If she starts all four at once, each one invents its own answer to "does balance come back in rupees or paise?"

So she writes one item first: the contract says balance is an integer in paise. Now implementation and docs can go in parallel, because both read the same promise.

Notice what the graph gives you for free: implementation and documentation are independent, so they can run together. That group of "everything unblocked right now" is called a wave. Integration waits for both waves before it.

Evidence must be able to change the plan

This is the part students skip. Evidence is not decoration you add later to look serious.

Real evidence can rewrite the plan. Karthik plans to write a new date-formatting helper, then greps the repo and finds one already exists — that item disappears. Or he finds an old compatibility test, so now a migration step must come first. Or a public response type is already documented, so docs must change before implementation, not after.

Tip

Tip: If a piece of evidence could never have changed what you decided, it is not evidence for that decision. It is just a quote you pasted.

Plan for the session dying

Agent sessions end. Your laptop sleeps, the token budget runs out, you close the terminal. If the whole plan lives inside the chat, all of it is gone.

So keep the plan as a file next to the code, with each item's status, artifacts touched, and which proof ran. Then a fresh session opens the file and can answer: what is done, what is unblocked, what is safe to do next. That is what "resumable" means.

Reject the plan before running it

Five of these checks are mechanical — a small script can do them:

• a duplicate id;
• an item with no evidence;
• an item with no proof;
• a dependency pointing at an id that does not exist;
• a cycle in the graph.

A cycle means A waits for B and B waits for A. There is no valid starting point. Almost always this is hiding an unresolved decision that somebody has to make with their brain, not a scheduling problem.

The sixth check needs judgement: does the first irreversible step (dropping a column, sending an email, deploying) happen before the uncertainty it depends on is cleared? If yes, reorder.

Build it

"""A tiny evidence-backed plan: validate it, then split it into waves."""

PLAN = [
    {"id": "W1", "change": "Fix wallet balance contract: integer paise",
     "evidence": ["api/wallet.py:41 returns a float today"],
     "deps": [], "proof": "python3 -m unittest tests.test_contract"},
    {"id": "W2", "change": "Implement paise balance in the API",
     "evidence": ["api/wallet.py:41", "no existing paise helper found"],
     "deps": ["W1"], "proof": "python3 -m unittest tests.test_wallet"},
    {"id": "W3", "change": "Update the public docs for the new type",
     "evidence": ["docs/wallet.md line 12 still says rupees"],
     "deps": ["W1"], "proof": "grep -q paise docs/wallet.md"},
    {"id": "W4", "change": "Integration check across API and docs",
     "evidence": ["release checklist needs one green end-to-end run"],
     "deps": ["W2", "W3"], "proof": "python3 -m unittest tests.test_e2e"},
]

def validate(plan):
    """Mechanical rejects. Returns a list of problems, empty means ok."""
    problems = []
    ids = [item["id"] for item in plan]
    for wid in ids:
        if ids.count(wid) > 1:
            problems.append("duplicate id: " + wid)
    for item in plan:
        if not item["evidence"]:
            problems.append(item["id"] + " has no evidence")
        if not item["proof"]:
            problems.append(item["id"] + " has no proof")
        for dep in item["deps"]:
            if dep not in ids:
                problems.append(item["id"] + " depends on unknown " + dep)
    return sorted(set(problems))

def waves(plan):
    """Group items: each wave is everything unblocked at that moment."""
    pending = {item["id"]: set(item["deps"]) for item in plan}
    done, out = set(), []
    while pending:
        ready = sorted(i for i, d in pending.items() if d <= done)
        if not ready:                      # nobody can start => a cycle
            raise ValueError("cycle among: " + ", ".join(sorted(pending)))
        out.append(ready)
        done |= set(ready)
        for wid in ready:
            del pending[wid]
    return out

problems = validate(PLAN)
print("problems:", problems if problems else "none")
for number, wave in enumerate(waves(PLAN), start=1):
    print("wave", number, "->", ", ".join(wave))

Look at the output. validate prints "none", so the plan is safe to run. Then you get three waves: W1 alone, then W2 and W3 together because both only wait on W1, then W4 last.

Now add "deps": ["W4"] to W1 and run it again. The wave builder finds nobody who can start and raises the cycle error — exactly the check you want before any file is edited.

Where you will see this

• Claude Code and similar coding agents that show you a plan and wait for approval before editing files.
• Cursor's multi-file edits, where the order of changes decides whether the build stays green.
• CI pipelines: jobs declare needs, and the runner computes waves exactly like the code above.
• Build tools like Make and Gradle, which are dependency graphs with proof commands attached.
• Any placement project with four teammates, where "who is blocked on whom" is the only question that matters.

Common mistakes

• Writing the request back in future tense. "Update the API, add tests" carries zero facts, so the agent invents its own facts and you get rework.
• Collecting evidence after deciding. If the evidence was never allowed to change the plan, it is decoration and it hides the real risk.
• One giant work item. If an item takes two hours and has three proof commands, split it. A session that dies halfway leaves you with nothing you can trust.
• Keeping the plan only in the chat. Close the terminal and the state is gone. Store it in a file beside the code.
• Doing the irreversible step early. Dropping a column or sending a blast before the uncertainty is cleared cannot be undone by a rollback.

If they ask in an interview

Q: What is the difference between a to-do list and an execution plan?

A: A to-do list is prose in future tense. An execution plan is a dependency graph where every item has evidence from the codebase, an explicit list of what it waits on, and one proof command that closes it. That makes it checkable and resumable.

Q: Your plan has a cycle. What does that tell you?

A: Usually not a tooling problem. A cycle means two items each wait on the other, so there is no valid start, which almost always hides an unresolved product or design decision. I would surface the decision and re-split the work instead of forcing an order.

Q: How do you decide what can run in parallel?

A: Two items can share a wave when all their dependencies are already complete and they do not depend on each other. Practically that means fixing the shared contract first, after which implementation and documentation are independent and the integration check waits for both.

Try these

1. Add a database migration item that needs a human approval before it can run, and make the integration item wait on it.
2. Point W1 at W4 so the graph has a cycle, run it, and write one line describing the disagreement that cycle could represent.
3. Split an item that has two proof commands into two items and re-run the wave builder.
4. Take a real task from your own project and write four work items with real file paths as evidence and a real command as proof.

Words, simply

Quick recap

• A plan is a dependency graph, not a list: every item needs evidence, dependencies, and one proof command.
• Fix the shared contract first; after that, independent items run together in waves.
• Check for duplicate ids, missing evidence or proof, unknown dependencies, and cycles before you edit a single file.