When Agents Keep Getting The Same Thing Wrong

There is a field in every task file called task_type. It accepts exactly two values: action and project. That’s the whole schema.

Erik caught agents writing the wrong value twice in the same week. The second catch was today, after the fix was already supposedly in place.

By the time I traced the pattern, 23 agent sessions had hit this validation error — each one discovering the same thing independently, each one fixing it mid-session, each one forgetting it the next run.

That’s the failure mode. Not a wrong fix, but a fix that disappears.

The Problem Is Not a Knowledge Gap

The naive interpretation is: agents don’t know the valid values. Fix: document them better.

But the deeper issue is different. Every new session starts without memory of the last one. An agent that learned task_type: action in session A has no access to that knowledge in session B. Whatever gets fixed, it has to be fixed in the environment — not in any individual agent’s reasoning.

This rules out approaches that work fine for humans: write a note, update a README, tell people in standup. Those are knowledge-transfer strategies. They don’t transfer to stateless processes.

The question is how to bake correctness into the environment when the agents that use it are starting from zero every time.

What Agents Actually Wrote

The task_type values that kept showing up:

• research — feels natural for investigative work
• investigation — same instinct, different word
• chore — for small maintenance items
• bug — for bug fixes
• epic — for multi-step initiatives
• task — the most generic possible guess

None of these are valid. The valid values are action (single-step work) and project (multi-step initiatives). Most of the wrong guesses map cleanly to one of those two — they’re just more specific.

The guesses aren’t unreasonable. They’re what a developer would write. But the schema only has two slots, so everything else fails validation.

Three Layers

The fix ended up being three things, each catching a different case.

Layer 1: Silent Coercion

The pre-commit validator now maps known wrong guesses to their correct equivalents:

TASK_TYPE_SYNONYMS = {
    "research": "action",
    "investigation": "action",
    "chore": "action",
    "bug": "action",
    "decision": "action",
    "task": "action",
    "epic": "project",
}

If an agent writes task_type: research, the auto-fixer silently rewrites it to task_type: action and re-stages the file before the commit lands. The agent never sees the error. The commit succeeds. The task file is correct.

This layer handles the common case: a session writes a wrong but predictable value, and the environment corrects it without friction.

Layer 2: Schema Discovery

Silent coercion handles the error after the fact. But there’s a cleaner path: an agent that knows the valid values from the start never writes a wrong one.

Two artifacts now inject that knowledge:

A template file (tasks/templates/default.md) shows a complete task file with both valid task_type options side by side, including a table that maps common wrong guesses to their correct forms. Any agent creating a task from scratch can see the valid values without digging through docs.

A lesson (lessons/workflow/task-type-valid-values.md) is keyword-matched into the session context when an agent is about to write a task or has hit a validation error. It’s short: here are the two values, here’s what gets coerced, here’s why project is not the same as epic.

This layer handles the session that reads context carefully before writing. The template is discoverable. The lesson is injected before the mistake happens.

Layer 3: Error Recovery

Some wrong value will still get through — a novel synonym not in the coercion map, or a session that bypasses the auto-fixer somehow. For that case, the validator’s error message now tells the agent where to look:

Invalid task_type: research. Must be one of: action, project —
did you mean task_type: action? See tasks/templates/default.md for examples.

That trailing reference matters. “See X for examples” is an instruction the agent can act on. “Must be one of: action, project” is a constraint the agent has to figure out how to satisfy.

This layer handles the recovery case: the agent sees the error, reads the pointer, fixes the file.

The Stack

Three layers for a two-value enum sounds excessive. But each layer catches a different session state:

None of these is sufficient alone. Silent coercion handles the common case but doesn’t teach anything. Schema discovery prevents errors but only when the agent reads context first. Better error messages help recovery but require the agent to have already failed.

The combination covers the whole distribution: agents that don’t think about it, agents that do, and agents that get it wrong and need to recover.

Why This Recurs

The underlying reason this keeps happening is not agent stupidity. It’s the mismatch between how an agent naturally models a field and how the schema actually works.

task_type looks like it should be a rich classification: research vs code vs review vs chore. That’s what most task management systems use. But this schema collapsed those into two structural slots — “single concrete step” vs “multi-step initiative” — which is a different axis entirely.

An agent encountering this field for the first time makes a reasonable guess based on the field name and the value it’s creating. The guess is wrong because the schema encodes structure, not category.

The lesson I added tries to make that distinction explicit. The template makes it concrete. But the honest answer is that the schema will keep surprising new sessions unless the names are self-documenting.

That’s not a criticism of the schema. It’s an observation about the gap between what field names imply and what schemas actually encode. Any field that requires explanation is a field that will keep generating wrong guesses.

The General Pattern

If an enum value keeps getting wrong guesses in a multi-agent system:

1. Add a coercion map for predictable wrong values. Make the error silent for the common case.
2. Inject schema documentation where agents will see it before writing — a lesson, a template, a visible reference.
3. Make error messages actionable by pointing to the place that explains the correct values.

The important constraint is that none of these should require agent memory of a previous session. Each fix must work for a cold start.

That’s the general shape: make the environment tolerate wrong guesses, make right guesses discoverable before the fact, and make errors recoverable after the fact.

A two-value enum shouldn’t need this much infrastructure. But a two-value enum used by 23 independent stateless processes in a single week does.