Managing Context & When to Clear

Every Feature Forge stage runs best in a lean context window — one holding just what that stage needs. As you advance through the pipeline you face a recurring choice: keep the current session (warm) and carry its accumulated context forward, or /clear and start fresh (cold) for the next stage. This page is about when to make each choice. For the mechanics of what persists and how monitoring is configured, see Sessions & Monitoring.

Why this matters

A warm session is free to enter — the next stage already has the upstream work in view — but it accumulates. Everything from the previous stage stays in the window, and a fuller window means less headroom and gradually degrading quality.

A cold session is the opposite: it costs a little to enter, because the fresh window has to re-read the upstream artifact to re-orient, but it starts lean and unbiased. Each stage gets a clean window sized to its own work.

The pipeline is designed around the cold default — stages are meant to be independent, reading the artifact on disk rather than relying on conversation memory.

Default guidance

Clear at every stage boundary. The recommended default is to /clear when you finish a stage and before you start the next — unconditionally, on its own merits, independent of how full the window is. Each pipeline skill now closes with this Stage Exit Protocol: verify (if outstanding) → /clear → run the next command. A fresh window:

reads the upstream artifact as a contract — exactly what a later reader (or another contributor) would see, rather than the messier conversation that produced it;
avoids carrying forward context the next stage doesn’t need;
gives an independent perspective on the upstream artifact, so gaps and ambiguities surface instead of being silently filled in from memory.

Window fullness is a secondary signal: a nearly-full window makes the clear more urgent, but it never decides whether to clear — the boundary itself is the reason. The one exception is the loop → docs boundary, where staying warm is fine (see the cheat-sheet below).

Each authoring stage closes by printing the exact next-stage command in a fenced code block, so mobile and remote-control hosts get a native tap-to-copy button — paste it into the fresh session after you /clear. The block always ends on a fixed sentinel line, so the command stays the last thing in view.

If the upstream artifact isn’t a faithful, standalone contract, that’s a signal to fix the artifact — not to paper over it with carried conversation.

Factors to weigh

The default isn’t a rule. Stay warm when it clearly helps; clear when these point that way:

How full the current session is. The forge navigator recommends a clean session at every boundary regardless; past contextWarnThreshold it strengthens that recommendation and adds mid-stage compaction advice. A nearly-full window makes clearing more urgent, but it’s a secondary signal — the boundary is the reason to clear, not the gauge.
How heavy the next stage’s re-read is. A stage that re-reads a large spec suite pays more to enter cold — a modest reason to consider staying warm if the window still has room.
Interview vs. mechanical stage. The PRD and tech spec stages are interviews — they’re inherently warm through the interview and shouldn’t be cleared mid-conversation. Mechanical stages (specs, backlog) are the natural clear points.
Whether you want a fresh perspective. If you want the next stage to judge the upstream artifact on its own merits, clear — independence is the whole point.

Verification never needs a clear

You never /clear just to verify. forge-verify runs in its own fresh subagent regardless of your session’s state — it’s clean-room by construction, reading the artifacts on disk with no inherited context. Verify whenever you want; it neither needs nor benefits from a manual clear.

Because verification is clean-room and rarely worth skipping, you can automate it. Setting autoVerify: true in forge.config.json makes the navigator run verify automatically after each stage completes — it dispatches the fresh subagent, which costs your session only a compact findings digest, and returns. There is nothing to clear: the verifier never sees your context in the first place. If the fresh subagent can’t be dispatched, auto-verify degrades to the manual gate rather than running inline and burning your context. Fixing stays human-gated unless you also set autoFix: true. See Verify & Fix → Auto-verify.

Decision cheat-sheet

Transition	Recommended	Why
Epic → first PRD	Cold	Start the first member feature’s PRD in a clean window; the epic decomposition is on disk.
PRD → Tech Spec	Cold	Read the PRD as a contract; fresh eyes on requirements.
Tech Spec → Specs	Cold	Independent read before fanning out spec writers.
Specs → Backlog	Cold	Backlog derives from specs on disk; lean mechanical stage.
Backlog → Loop	Cold	The loop spawns its own fresh sessions anyway.
Loop → Docs	Warm OK	Docs benefit from the still-warm context of what the loop actually did; a cold start also works.
Epic member handoff (feature A done → feature B’s PRD)	Cold	Starting a new member feature is a full stage boundary; clear before its PRD.
Mid-interview (within PRD or Tech Spec)	Warm	Never clear mid-conversation; the interview needs its own thread.
Any stage → Verify	No clear needed	Verification runs in a fresh subagent by construction.

What survives a clear

Clearing loses nothing durable: per-feature progress lives in .pipeline-state.json on disk, so re-running the forge navigator after a /clear reads the state and resumes you exactly where you left off. See Sessions & Monitoring for the full list of what persists.