Pattern Matrix/White Paper/M3

M3 · Progress Tracking

The problem it solves

An LLM has no real working memory. Its "memory" lives entirely in the context window, and the context window has a U-shaped attention profile—the middle section gets drowned out. When a long task runs for two or three hours and a stretch of debugging or detail-chasing crops up in the middle, the remaining tasks in the original plan are easily forgotten by attention. A common failure: the agent breaks down the first three files, then sinks into a small bug for twenty-odd turns, and once it finishes, goes straight to writing tests, forgetting that a fourth file in the original plan was never created.

Progress tracking catches this with engineering means: it forces the todos to be written out explicitly and repeatedly prompts the agent to look at its own list. The key point is that the list is not for humans, it is for the agent itself—an agent reading its own structured todos is far more reliable than reading its own conversation history from thirty turns ago, riddled with noise.

Why the coordinate is "Memory × Orchestrate"

• Vertical axis · Memory: It gives the agent a "work log" that preserves task context across steps. This is the simplest form of memory (session memory)—remembering "what I just did, what I'm doing now, what comes next."
• Horizontal axis · Orchestrate: Progress tracking does not sit inside any single task step; it cuts across all steps. It maintains a todo state that runs through the entire long task, coordinating the agent so that it does not drift across multiple steps, can resume when interrupted, and can return when it jumps ahead. This "standing above all the steps and coordinating" is exactly what Orchestrate does, not the Chain approach where one step hands its result to the next.

Core mechanism

1. A minimal state machine: The core schema is extremely lean—task description, a status enum (pending / in_progress / completed), and a progressive form. The hard constraint of the state machine is that only one item is in_progress at any moment; a single-threaded agent can focus on only one thing at a time.
2. Externalizing state into the conversation flow: On every turn, progress is written out so that both the agent and the user can see it. This is the central move against the LLM's working-memory deficit—offloading the task from working memory to external storage.
3. Automatic clearing when everything is done: Once all todos are completed, the list is cleared automatically, so the agent does not keep seeing a stale "all done" list that interferes with judgment on a new task. This is counterintuitive but necessary, because an LLM has a "seen is attended to" property.
4. Framework-level forced nudge: Teaching the agent to write todos through the prompt alone is not enough; the framework layer must have a mechanism. Two industrial implementations exist: one is the verification nudge (when a list of three or more items is closed without a verification step, a reminder is appended automatically), the other is context-loss detection (when a complex task is being done without any todos written, a reminder is injected automatically, and if the agent keeps not writing them, the pressure escalates progressively).
5. Isolation by agent / session: Each agent or sub-agent maintains its own todo pool, so that a sub-agent's detail todos do not pollute the main agent's high-level list.

Production scenarios it fits

• Multi-step long tasks: Tasks with three or more steps, spanning many turns, prone to amnesia after detail-chasing in the middle. Code refactoring, multi-file rework, complex debugging.
• Recoverable long flows: Scenarios where a task may crash midway and need to resume. After progress is persisted, the second session reads the progress, skips what is completed, and recovers from the interrupted step without redoing work.
• Tasks driven forward over multiple weeks: Scenarios where the same goal is advanced across several weeks (such as investment research forming a judgment on a single stock), requiring a two-layer todo—the high-level research plan persists across weeks, while concrete actions within a session are merged back into the high level once done.

Where it goes wrong

• Forcing it onto a single simple task: Work of three steps or fewer, plain conversation, and one-off Q&A do not need todos.
• Allowing multiple in_progress: Violates the hard constraint of the state machine. When an engineer complains "I want to do them in parallel," it is usually a false need—either the task should be split across multiple agents, or it should be arranged into a chain and done in sequence.
• Missing the active-form field: When the UI shows "what is being done," mechanically appending -ing to a verb produces splices like "Fix cache bug...ing." Using a progressive-form field forces the verb form to be thought through at the moment the todo is written.
• Main agent and sub-agent sharing one pool: When the main agent looks at its own list, it gets drowned by five to ten detail todos from sub-agents, its attention contested by irrelevant granularity. Sub-agents must have their own todos.
• No framework-level nudge: When the agent does a five-step task with no todos written at all and the framework does not remind it, the amnesia happens as before. The three tiers of the nudge's progressive pressure (suggest → require → enforce) need clear boundaries.

Key metrics

• Amnesia rate (the lower the healthier): the fraction of long tasks in which the agent drops a step from the original plan. This is the primary indicator of whether progress tracking is done right; no matter how pretty the todo UI is, it cannot rescue a high amnesia rate.
• Verification-step coverage (healthy range near 100%): the fraction of tasks with three or more items that include a verification step before closing. The verification nudge drives this metric directly.
• Resume success rate (healthy range ≥ 95%): the fraction of post-crash recoveries that resume from progress without redoing completed steps.
• Single-in_progress compliance rate (healthy range 100%): the share of moments at which only one item is in_progress; any violation means the state machine has a bug.

Minimal implementation skeleton

TodoItem: content (verb base form) / active_form (progressive) / status (pending|in_progress|completed)
            TodoList (isolated by owner_id):
                start(id)    → mark in_progress, automatically pause any other in_progress back to pending (only one at a time)
                complete(id) → mark completed
                all_done()   → if all completed, clear automatically
            ProgressTracker (framework-level enforcement):
                context_loss_detected → complex task but no todos written → inject reminder
                nudge progression: suggest → require → enforce (halting)
                verification_nudge   → 3+ list closing without a verification step → append reminder
            Persistence: incremental append-only + periodic snapshot + session fallback
            

Four points for engineering implementation: only one in_progress at a time must be enforced; estimate complexity with a cheap model rather than by counting verbs; the three tiers of the nudge's progressive pressure need clear boundaries; isolate the TodoList by agent_id rather than sharing it.

Enterprise implementation example

A buy-side research firm's investment-research agent has to advance a judgment on a single stock alongside the analyst over four to twelve weeks. An ordinary single-layer todo is not enough; here a "unified session state plane" is needed. The SessionState is the mechanical-parameter state—a strict key-value structure that records each stock's research plan, current investment thesis, key risks, and counter-views, ensuring that during continuous multi-step analysis the input to each step has a unique, auditable source (for example, "which day's earnings data was used"). The SessionNarrative is the narrative-alignment state—a natural-language summary that records "what we are doing overall and which dimension this round advanced," resolving the question of where output is written back for later sessions to consume. The accompanying design includes: a two-layer todo (the research plan persists across weeks while session tasks merge back once done); state stored as git-friendly markdown (the analyst can git diff to see each week's changes); key risks and counter-views never cleared (injected as the system prompt on every session); a four-state machine (an extra needs_review state, where the fund manager must review before something counts as completed, satisfying the regulatory requirement that "every judgment is reviewed by a person"); active forms carrying data timestamps (forcing the agent to check "is the data I used fresh enough"); and an automatic weekly-report merge on weekends.

Relationship to other patterns

• Layered Retention (M1): Progress tracking is the hottest layer within the hierarchy. The todo list is the agent's register—three to seven items, frequently updated, loaded on every inference—the part of the session layer dedicated to managing "how far the work has progressed."
• Failure Diary (M4): A twin relationship, both in the Loop column. Progress tracking manages "the path of what was done right," the failure diary manages "the pitfalls stepped into." One records successful steps, the other records failure cases.
• Plan-and-Execute (Reasoning module): Progress tracking is the runtime twin of Plan. Planning produces a one-shot static list of "what we want to do"; progress tracking maintains, in a loop, the dynamic state of "how far we've gotten." Two different things—do not conflate them.
• Hooks Pipeline (Governance module): The framework-level nudge and persistence hook points fit the hook mechanism naturally and can be implemented with PreToolUse / PostToolUse hooks.

What this pattern teaches

Progress tracking is not progress visualization for the user; it is external working memory for the agent—an engineering patch for the working-memory deficit of the agent era. Without it, the smarter the agent, the more dangerous it becomes in long tasks.

This page is part of the ADPS pattern white papers. Back to the pattern matrix, or see the runnable code catalog.