Token Efficiency

When to clear context, how to keep sessions clean, and the 30-40% insight for consistent quality

beginner

The Context Window Problem

Claude’s context window fills up over a session. As it fills past 50-70%, output quality degrades — responses become rushed, less thorough, miss edge cases. The agent isn’t tired; it’s just running out of room.

Every tool call, file read, and code block consumes tokens. A long planning discussion before execution means the executor starts with less room. A multi-plan session without clearing means later plans get lower quality attention than earlier ones.

The 30-40% Rule

Start each new execution context below 30-40% usage. The quality difference is real and measurable:

  • Fresh context (0-30%): Thorough, comprehensive. Catches edge cases. Follows instructions precisely.
  • Mid context (30-60%): Solid. Occasionally skips secondary concerns.
  • Heavy context (60-80%): Noticeably rushed. Skips verification steps. Less creative problem-solving.
  • Overloaded (80%+): Minimal effort. Misses obvious issues. Short answers.

GSD plans are designed to complete within ~50% of a context window. That’s the reason plans have 2-3 tasks instead of 6-8 — keeping each plan within budget preserves peak quality throughout execution.

When to /clear

These are the signals that it’s time to clear context and start fresh:

  1. Starting a new plan execution — each plan deserves a fresh context
  2. Switching from planning to executing — discussion tokens don’t help execution
  3. After a long discussion that generated substantial output
  4. Any time the agent starts giving vague or incomplete answers — this is the clearest signal

After clearing, run /gsd:resume-work to re-orient the agent. It reads STATE.md and brings the agent back up to speed without re-reading everything.

$ /gsd:resume-work

/gsd:resume-work re-orients the agent with current STATE.md context after a clear. It costs a fraction of the tokens that accumulating context drift would cost.

What NOT to Clear

Don’t clear mid-plan if you’re in the middle of a multi-step task. The executor needs continuity within a plan — it’s tracking deviations, pending verifications, and working state.

Finish the current task or reach a checkpoint first. Then clear between plans.

The right cadence: one clear per plan boundary. Execute a plan, clear, resume-work, execute the next plan. This keeps every plan execution at peak quality without losing continuity.