Writing things down

Plans, tasks, and todos

Break a goal into executable steps, track linked work through completion, and keep the smaller standalone items that do not need a full plan.

“make a plan for the billing migration”

Steps, scope, and risks — to read before anything changes.

“what's still open on billing?”

The plan's remaining tasks.

“add a todo to rename the config flag”

A standalone note, no plan attached.

Plans are how you give an assistant room to continue without giving it a vague blank cheque. You agree on the outcome, constraints, finish lines, and verification; a current or future agent can own the permitted execution and report where the plan blocks.

Plans

A plan is a goal broken into ordered steps, each with enough detail that someone else could execute it — scope, the concrete work, how you'd know it was done.

That last part is what makes plans useful rather than decorative. "Add rate limiting" is a wish. "Add a token bucket to the gateway middleware, 100 req/min per key, with a test covering the burst case" is a step.

The normal save flow creates one linked task per step. An API client can opt out of task creation, so integrations should not infer tasks from plan text.

A plan can be a draft, active, completed, or archived. Keep it in draft while the approach is still under review; activate it when the steps are the agreed path. Completing a plan says its goal was achieved. Archiving says it is no longer active without pretending the work succeeded.

What belongs in each step

Someone arriving in a fresh session should be able to execute a step without asking what you meant. Include:

  • the scope and affected area;
  • the concrete change or investigation;
  • the acceptance criteria;
  • the verification command or evidence;
  • important risk, dependency, or rollback information.

Attach the durable material that removes ambiguity. Plans can link documents, diagrams, runbooks, and handoffs. The linked item remains its own authoritative record rather than being pasted into the plan.

A plan another session can execute

Take a signing-key rotation. “Rotate the key” is not a plan; it hides the compatibility window and the point of no return. A usable plan might contain:

  1. Inventory consumers. Identify every service and environment that verifies the key. Finish when the list is checked against current deployment configuration.
  2. Add dual-key verification. Accept the current and next public key. Verify old and newly issued tokens, and document the rollback switch.
  3. Deploy and observe. Roll out the verifier first. Check authentication failures and stop if they cross the agreed threshold.
  4. Change the signer. Issue new tokens with the next key while continuing to accept the old one.
  5. Retire the old key. Wait through the maximum token lifetime, verify no old-key traffic remains, then revoke it.

Each step becomes a linked task with its own status. Attach the rotation runbook, the decision that set the overlap window, and the reminder scheduled for the start of the rotation—not the expiry date.

If step three reveals an unexpected client, mark the task blocked and name the client. Do not close the plan because four of five steps happened; completion means the old key is safely retired and the final verification passed.

Tasks

A task belongs to a plan step and carries a status — pending, in progress, completed, blocked, or cancelled. Between them you can see what's left without reading the plan.

Tasks are what you hand to an agent. "Do step three" works because step three has a description.

Tasks can be reordered as the implementation changes. A blocked task should say what it is waiting on, not merely change color in a dashboard. Cancelling a task preserves that it was considered and deliberately dropped.

Todos

Separate, deliberately. A todo is a lightweight standalone item with no plan step behind it — the thing you noticed while doing something else. It can carry a priority, status, and due date without becoming a structured plan.

Use a ticket rather than a todo when someone needs assignment, labels, an external issue reference, a parent or sprint relationship, or a richer status lifecycle.

Why not a markdown file

A plan in a file is not part of ContextStream's plan/task index. Stored as a shared plan, it is available to authorized sessions, editors, and teammates, and an agent can pick up the next task without you re-explaining the goal.

They outlive the session

Start a plan today and open a fresh connected session tomorrow; the plan and its open tasks are still there. They belong to the project record, not one assistant's chat history.

Authorized team views can collect plans' tasks and standalone todos across the workspace. Personal scope remains available when the work should follow only you.

Updating progress

Close tasks as their acceptance criteria are met, not at the end of the week from memory. If the implementation changes the plan, update the step and its task together so a later session does not read conflicting instructions.

At completion, check the plan goal itself. Ten closed tasks do not prove the outcome if the verification step failed.

If it doesn't work

The plan is too vague to execute. Steps need acceptance criteria. Redraft with a finish line per step.

Tasks are done but still open. Status is updated as work completes, but a task finished by hand needs closing. Say "close the tasks for step two".

I have plans I don't recognise. Old plans stay active until completed or archived. Archive the stale ones.

A task and its plan disagree. Update the plan step and linked task in the same pass. Do not leave the next agent to choose between them.

The plan is complete but the decision is missing. A plan records intended work, not necessarily why one architecture won. Record the important choice separately as a decision.

Next