Human Todos

Human Todos is a pattern I originally picked up from Monday’s article on splitting a monolithic JavaScript client into separate services¹. The pattern feels like a critical tool for teams that need to validate coding agent outputs at scale. Yet I haven’t seen many teams exploring this strategy.

Monday’s engineers originally used the pattern to catch behavioral drift during business logic rewrites. I’ve expanded it to add review points and implementation steps for humans. This page describes how you can get started.

If PRs from coding agents look exactly like PRs from your human colleagues, you will hit review bottlenecks unless you start letting things through without actually reading the code. This is where you can use Human Todos as review points.

If a coding agent has made a change that is critical for you to review, and reviewing it takes longer than making the change yourself, why are you delegating the work to a coding agent in the first place? This is where you can use Human Todos as implementation steps.

Human Todos as review points

Using Human Todos as review points is one way to make it easier to identify the lines of code where you need to pay closer attention.

The original pattern from Monday works like this:

• When extracting files from a monolith into separate services, instruct the agent to add HUMAN_TODO comments whenever the original implementation needs to change because of the constraints of the new environment.
• The comments should include the original implementation, a description of the change, and an explanation of how it affects behavior.
• Finally, introduce a linter rule that checks for the existence of those comments.

Here is how I would expand the pattern:

• Discuss with your team which layers you are most worried about your coding agent diverging from the spec in.
• During or after implementation, instruct a coding agent to add HUMAN_TODO comments whenever changes are made to those layers.
• Define what helpful comments look like for your team.
• Add linter rules that catch those HUMAN_TODO comments.

A major consideration is whether you add the HUMAN_TODOs during or after implementation. “During” requires you to provide instructions and skills to the main agent. “After” allows you to limit the number of instructions and skills the main agent loads. Because of this, I personally prefer adding the comments “after” through a user-invokable skill.

Example

Here is a user-invokable skill you can use to start experimenting with Human Todos as review points.

This example is made for NestJS. Change the example inside the <example> tags to match your tech stack. For the linter rule, ask your coding agent to generate one for you.

---
name: human-todos
description: Flag API endpoint changes that need human review by adding HUMAN_TODO comments above the affected controller methods
---

Compare the current changes against the base branch. 

For each existing controller method whose behavior changed, add a comment directly above the method in the format:

	// HUMAN_TODO: <short description of the change>

Do not add HUMAN_TODO comments for newly created endpoints/methods.

<example>
// HUMAN_TODO: Added pagination to GET /books 
@Get() async findAll(@Query() pageOptionsDto: PageOptionsDto): Promise<PageDto<BookDto[]>> 
{
	return this.bookService.findAll(pageOptionsDto); 
} 
</example>

Human Todos as implementation steps

Personally, I don’t let coding agents install or set up new dependencies for me. Doing so introduces significant architectural changes and requires me to review documentation to make sure everything is configured according to the most up-to-date recommendations.

Some dependencies also come with setup scripts that automatically generate many files. But when you review a PR from a coding agent, you can’t tell which files were generated by the setup script and are therefore higher-trust, and which were generated by the agent and are therefore lower-trust.

The pattern works like this:

• Discuss with your team which steps humans should always perform to bake human review directly into the implementation process.
• Instruct a coding agent to add those steps as Human Todos.
• Prevent the coding agent to continue work until the Human Todos are resolved.

If you use planning you can incorporate this step into the planning process:

• When generating a plan.md file, instruct the coding agent to add Human Todos there.
• Instruct coding agents to refuse to implement a plan.md if it contains unresolved Human Todos.
• Add a user-invokable skill that updates the plan.md after the human has completed the todos.

Example

The example below is implemented purely through skills to showcase the idea. In practice, you can replace the HUMAN_TODO check with a deterministic script that checks for unresolved todos, as long as the formatting of your plans stays consistent. This will save tokens and produce more reliable results.

And yes, all of these steps could also be chained into a single loop using a Bash script.

First, use the planning skill to generate an implementation plan. plan.example.md is an example plan that in our case would contain at least one Human Todo to properly communicate the format:

---
name: create-plan
description: Generate a written implementation plan for a change, flagging steps that need human review
---

Generate a plan for the following change: $ARGUMENTS

For any step that involves installing or adding a new dependency, prefix it with `**HUMAN_TODO:**`.

Write the plan to `docs/plan.md`.

Use `docs/examples/plan.example.md` as a format reference.

After you have completed the todos assigned to you by the agent, run the resolve skill:

---
name: resolve-human-todos
description: Mark resolved HUMAN_TODOs in docs/plan.md after human review
---

Read `docs/plan.md`. Ask the human which HUMAN_TODO items have been addressed if it isn't already clear from context.

For each confirmed-resolved item, remove its `**HUMAN_TODO:**` marker, keeping the underlying step description intact.
Leave any unconfirmed HUMAN_TODOs untouched.

Finally, send the agent off to work:

---
name: implement-plan
description: Implement a plan from docs/plan.md, enforcing unresolved HUMAN_TODOs
---

Read `docs/plan.md`.

Scan the plan for any unresolved `**HUMAN_TODO:**` markers before implementing anything. 
If any are found, stop immediately without implementing any part of the plan, and list the unresolved items so the human can address them.

If there are no unresolved HUMAN_TODOs, implement the plan step by step.