Less forceful todowrite tool guidance would fit 2026 models better

Description

My agent, based on Qwen3.8-Flash-Next, tends to relatively frequently complain about the system "nagging" it to use todo lists. Today, I asked the model what it meant, and it turns out that the model feels that the instructions push overly hard to use the tool, and doesn't leave it enough latitude to not use it. This creates unnecessary reasoning at some conversation turns, as the model argues with itself about it.

Upon investigation, it turned out that todowrite instructions are very different from rest of the tools, it is the only one with examples, rules, etc. sections. The others read differently, and don't seem to cause an issue. Here might be a proportionate todowrite.txt to replace the old one, written by that model. There are some judgement calls here for the model to make, and an internal contradiction about blocked state allowing multiple in_progress items, but probably the model can work this out.

Maintain a task list for multi-step work so progress stays visible.

Use it when work has 3+ distinct steps, when the user gives multiple tasks, or when
asked. Skip for a single straightforward task, purely informational requests, or when
tracking adds nothing.

- Exactly one `in_progress` at a time; update status as work moves, don't batch.
- `completed` only when the work — including any verification — is actually done,
  never from intent.
- Blocked: keep the item `in_progress` and add a todo describing the blocker.
- Items specific and actionable; preserve user-supplied commands verbatim.

The old file is provided here for reference:

Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.

## When to use
Use proactively when:
- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)
- The work is non-trivial and benefits from planning
- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
- New instructions arrive - capture them as todos
- You start a task - mark it `in_progress` (only one at a time) before working
- You finish a task - mark it `completed` and add any follow-ups discovered during the work

## When NOT to use
Skip when:
- The work is a single, straightforward task (or <3 trivial steps)
- The request is purely informational or conversational
- Tracking adds no organizational value

## States
- `pending` - not started
- `in_progress` - actively working (exactly ONE at a time)
- `completed` - finished successfully
- `cancelled` - no longer needed

## Rules
- Update status in real time; don't batch completions
- Mark `completed` only after the required work is actually done, including any required verification. Never based on intent.
- Keep exactly one `in_progress` while work remains
- If blocked or partial, keep it `in_progress` and add a follow-up todo describing the blocker
- Preserve user-provided commands verbatim (flags, args, order)
- Items should be specific and actionable; break large work into smaller steps

## Examples

Use it:
- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
- "Implement registration, catalog, cart, checkout" -> multiple complex features

Skip it:
- "How do I print Hello World in Python?" -> informational
- "Add a comment to calculateTotal" -> single edit
- "Run npm install and tell me what happened" -> one command

When in doubt, use it.

Plugins

None

OpenCode version

1.18.26

Steps to reproduce

I tend to get vague complaints about "nagging" frequently enough that I investigated why the model says this. Originally, I though it is invisible system-reminder messages nagging it, but based on what the model says, it is really the language of this one todowrite tool that cause it to argue against its instructions. For example, I asked the model to study implementation of a java library to figure out how to do something that isn't documented with it, and during its investigation, it wrote like this:

Todo list? Multi-step but investigation-centric; we're deep already. Skip — no actually the reminder nags; but the work is nearly done: 3 verification steps + probe + write-up. Use a short todo list? No — the task is "investigate"; we're in the last 20%; a todo list adds little. Proceed.

There is no actual reminder here, despite what it says, I think. I originally assumed that these are from <system-reminder>s that are scheduled to arrive from time to time, to remind the model that it hasn't e.g. created a todo list yet, but apparently this is not how opencode behaves, and I found neither such code nor did the model claim upon asking that there were such actual reminders. Rather, the model focused on these two lines, and said they were the most problematic:

The "Use proactively" and "When in doubt, use it" lines are the actual nag — they push me toward creating a todo list even when I judge it low-value (like mid-investigation here).

Screenshot and/or share link

No response

Operating System

No response

Terminal

No response