Qualify the retry-cost reuse guarantee in compaction documentation for marker-write failures #3082

What happened

On PR #2995, CodeRabbit flagged that docs/user_doc/conversation_compaction.md (lines 211–216) states a retry will reuse the stored summary and avoid another charge, but this guarantee does not hold when the marker write fails after the summarization call succeeds. In that case, the user is charged, the summary is not persisted, and a retry will make and charge another summarization call. The same unqualified claim appears in docs/devel_doc/ARCHITECTURE.md. The PR author acknowledged this edge case in the PR body's "Known limits" section but the user-facing documentation was not updated. The PR was merged with the CodeRabbit comment unresolved.

What could go better

The documentation makes an unqualified promise that retries avoid double-charging, which is incorrect in the marker-write-failure edge case. This is a documentation accuracy issue — the behavior itself is correct (and documented in the PR body), but the user-facing and developer-facing docs need a qualification. Confidence is high: the CodeRabbit analysis is correct and the PR author's own "Known limits" section confirms the edge case exists.

Proposed change

In docs/user_doc/conversation_compaction.md (around lines 211–216), qualify the retry-cost guarantee: state that reuse avoids another charge only when summary persistence (including the marker write) succeeds. In docs/devel_doc/ARCHITECTURE.md (around line 279), make the same qualification. Preserve the existing description for the common case (successful persistence) while adding a brief note about the marker-write-failure edge case.

Validation criteria

Both documentation files explicitly state that the retry-reuse guarantee depends on successful summary persistence. A reviewer reading the docs can understand when a retry may incur an additional charge.

Related issues checked

Searched: retry cost compaction summarization; marker write failure compaction documentation
No overlapping issues found.

Generated by retro agent from #2995