[DOCS] Context window docs missing auto-compaction circuit breaker behavior (stops after 3 failures)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/how-claude-code-works

Section/Topic

"The context window" section — "When context fills up" subsection

Current Documentation

The "When context fills up" section describes automatic compaction:

"Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost."

There is no mention of what happens when compaction itself fails, how many retries occur, or when the process stops.

What's Wrong or Missing?

Auto-compaction can fail (network error, model timeout, etc.). Prior to v2.1.76, Claude Code would retry indefinitely, leaving sessions in a degraded state. Version 2.1.76 introduced a circuit breaker:

"Fixed auto-compaction retrying indefinitely after consecutive failures — a circuit breaker now stops after 3 attempts"

This behavior is not documented anywhere in the user-facing reference pages. Users experiencing repeated compaction failures have no documentation explaining:

• That auto-compaction will stop retrying after 3 consecutive failures
• What state the session is left in when the circuit breaker trips
• How to recover (e.g., manual /compact, starting a new session, or addressing the root cause)

Suggested Improvement

Add a failure-handling note to the "When context fills up" section in how-claude-code-works.md:

After the current paragraph on automatic compaction, add:

Compaction failure handling If auto-compaction fails (for example, due to a network error or model timeout), Claude Code retries up to 3 times. After 3 consecutive failures, auto-compaction stops for the session to avoid degrading performance. If this happens, run /compact manually to compact the conversation, or start a new session with /clear.

Also consider adding a troubleshooting entry to troubleshooting.md:

Auto-compaction stopped working mid-session If you see repeated compaction failure messages, the circuit breaker may have tripped after 3 consecutive failures. Run /compact to compact manually or /clear to start a fresh session.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/how-claude-code-works | "When context fills up" subsection — no failure-handling or retry documentation |
| https://code.claude.com/docs/en/troubleshooting | No entry for compaction failure or circuit breaker |

Total scope: 2 pages affected

Source: Changelog v2.1.76

Fixed auto-compaction retrying indefinitely after consecutive failures — a circuit breaker now stops after 3 attempts