feat(roadmap): a parser failure gets one smaller-edit message #3571

Problem or Motivation

Three stops (#2554, #2579 and #3318) had class parser (XML syntax error ... unexpected EOF) and cost 1.77M input tokens. The upstream report ollama/ollama PR 18571 says the failure is deterministic for one conversation. _turn sends the same conversation again with no new text (CONST_ROADMAP_IMPLEMENT_MODEL_RESENDS is 1), so the resend cannot help. Split from #3053.

Proposed Solution & Architectural Design

• On class parser, the resend carries one message that asks for a smaller edit.
• A second parser failure stops the step with class parser. The work of the group stays as wip: commits.
• Acceptance: a stub model that fails twice with a parser error stops the step after one smaller-edit message; the message is in the second request.

Target Subsystem

src/devops_cli/roadmap/implement_step.py (_run_agent, _resend_after).

Existing Tool Considered

No open tool covers a smaller-edit message for a parser error of a provider. The project builds it: about 30000 tokens to build, 2000 each quarter to keep, 6000 to fix one miss, about 2 hours.

Source: #3053

Proposed design

Problem statement

A parser error of a provider is deterministic for one conversation. The step resends a failed request with one message that asks for a smaller edit. A second parser failure must stop the step with class parser and keep the wip: commits. The tree at this commit still moves a parser failure to the next tier, so the step can continue instead of stopping.

Acceptance criteria

Requirement: Parser resend asks for a smaller edit

On a parser failure of a model call, the step SHALL send the failed request again with one message that asks for a smaller edit.

Scenario: The second request holds the smaller-edit message

• WHEN the stub model fails the first request with a parser error and answers the second request
• THEN the second request ends with the implement_parser_smaller_edit text, and the step made two requests

Requirement: A second parser failure stops the step

When the request that carries the smaller-edit message fails with a parser error, the step SHALL stop with class parser and move no tier.

Scenario: Two parser failures stop the step on the first tier

• WHEN the stub model fails both requests with a parser error and the ladder names two tiers
• THEN the outcome is stopped with failure_class parser, the step made two requests, and tiers names only the first tier

Requirement: A parser stop keeps the wip commits

A step that stops with class parser SHALL keep the wip: commits of its group and discard only the work after the last one.

Scenario: The checkout is at the last wip commit

• WHEN the agent ticked a task whose verification passed and the stub model then failed with a parser error twice
• THEN the checkout is at the last wip: commit, and the stop reports the discarded diff

Requirement: Other in-stream failures keep the plain resend

A failure that is not of class parser SHALL send the request again with the same messages and no new text.

Scenario: An in-stream 400 that is not a parser error adds no message

• WHEN the stub model fails the first request with an in-stream 400 that the classifier does not read as parser
• THEN the second request holds the same messages as the first, and no smaller-edit text

Existing Tool Considered

No alternatives check has run. No open, maintained tool or library covers a smaller-edit message for a provider parser error. The project builds it: about 30,000 tokens to build, 2,000 each quarter to keep, 6,000 to fix one miss, about 2 hours. The tree already holds the message and the resend, so the remaining change is small.

Key questions

• Which failure class gets the smaller-edit message?: Only class parser. _run_turn sets the class with _run_class, which calls classify_failure on the reason. The parser rule comes before the provider rule, because an Ollama that cannot parse a tool call answers with HTTP 400. _run_agent reads the class in run.failure_class. [sources: src/devops_cli/roadmap/implement_step.py, src/devops_cli/roadmap/failure.py]
• How does the smaller-edit message reach the second request?: _ask_smaller_edit appends one UserPromptPart with MESSAGES.roadmap.implement_parser_smaller_edit to the last ModelRequest of the resend conversation. _run_agent then calls _run_turn with None, so the second request ends with that text. (best practice) [sources: src/devops_cli/roadmap/implement_step.py]
  • Chosen: Append a UserPromptPart in _ask_smaller_edit. It adds one part to the request that _resend_after returns, and _run_turn already resumes a conversation.
  • Rejected: Pass the text as the message of _run_turn. It starts a new user turn, not a resend of the failed request.
  • Rejected: Append a whole ModelRequest to the conversation. It builds a message by hand and puts the text outside the failed request.
• Where does the text of the smaller-edit message live?: In MESSAGES.roadmap.implement_parser_smaller_edit, beside implement_repair_turn. It asks for one file or one small part of a file in each tool call, and it is bounded. (best practice) [sources: src/devops_cli/lang/en/messages.py, src/devops_cli/roadmap/implement_step.py]
  • Chosen: Add implement_parser_smaller_edit to MESSAGES.roadmap. The step keeps its texts in MESSAGES.roadmap, and the text says only what a parser failure needs.
  • Rejected: Reuse implement_repair_turn. It names a failed check and the paths of a repair turn, and a parser failure has neither.
• How many sends does one parser failure get, and do they count in the limits?: One. CONST_ROADMAP_IMPLEMENT_MODEL_RESENDS stays 1. _resend_after adds the failed request and the replies before it to the usage of the conversation, so the request limit counts every send. [sources: src/devops_cli/config/constants.py, src/devops_cli/roadmap/implement_step.py]
• Does a parser failure try the next tier of the ladder?: No. A second parser failure must stop the step with class parser and must not run the next tier. _moves_tier must return false for a parser failure, even when provider_error is set, because the parser failure is deterministic for one conversation and another tier would get the same conversation. (best practice) [sources: src/devops_cli/roadmap/failure.py, src/devops_cli/roadmap/implement_step.py, openspec/changes/3060-a-model-ladder-for-retries-with/design.md]
  • Chosen: Stop on parser and move no tier. The item states the stop, and the work of the group stays as wip: commits. This overrides the CHANGE_TIER default of feat(roadmap): a model ladder for retries, with the tier chosen per attempt #3060 for this class.
  • Rejected: Keep change_tier for parser. A tier move continues the step with the same conversation, which fails the same way.
• What delivers this item, and what happens when that pull request merges?: The item delivers with its own pull request. The pull request changes _moves_tier so a parser failure moves no tier, and adds the regression tests. The tree at this commit already holds _ask_smaller_edit and implement_parser_smaller_edit. When the pull request merges, it closes feat(roadmap): a parser failure gets one smaller-edit message #3571, and no separate close is needed. (best practice) [sources: src/devops_cli/roadmap/implement_step.py, src/devops_cli/lang/en/messages.py]
  • Chosen: Deliver with its own pull request that stops the tier move. The smaller-edit resend is in the tree, but _moves_tier still moves a parser failure to the next tier.
  • Rejected: Wait on feat(roadmap): every step repairs before it gives up, in bounded rounds #3053 and close as delivered. The tree already holds the feat(roadmap): every step repairs before it gives up, in bounded rounds #3053 behavior, and the remaining _moves_tier defect needs a change.

Fit

Fits in one pull request.

Suspected block

None.

Dependencies

None.