Chapter 14: Context Management: Using /clear and the 'Three-Stage' Rebuild

Adapted public course. Concepts, procedures and examples are adapted from the internal textbook. Case sizes, timings, improvement figures and target thresholds are illustrative, not site delivery results or universal standards. Verify tools, platforms and skills in your environment. Prompts do not grant permissions and retry counts do not authorize recovery. Preserve work and verify targets, sharing and external-state effects first.

Lesson explanation

14.1 When You Must Clear the Session (Five Hard Criteria)

Many developers get into the habit of using a single IDE chat window or web dialog from the day the project is created all the way to launch, expecting the AI to remember every cause and effect along the way. This is an utterly disastrous practice.

Repeated failed attempts and abandoned logic can crowd out relevant context and disrupt later judgment. Verified discoveries remain valuable and should be saved in documents. Length alone does not inevitably cause severe hallucination; risk depends on relevance, the model budget, and context management. It is like standing on a construction site piled high with demolition debris, discarded sketches, and historical junk, and expecting the implementation crew to still see the foundation line at their feet with precision.

We call this discipline the “context guillotine” because it interrupts ineffective attempts. The following are this book’s operational triggers. When one fires, stop ineffective work, save verified state and unresolved questions, then clear, reload, restate, and verify:

1. The AI starts “going in circles”: the same problem has been revisited more than three times without resolution, or fixing one bug introduces a new bug;
2. A “correction tug-of-war” has occurred: you and the AI have gone through more than two rounds of “correction—justification” dialogue on some issue, with no sign of convergence;
3. You detect “confirmation bias” signals: the AI is defending a clearly wrong approach, and may even start “showing off” — using convoluted logic to paper over its mistakes;
4. A milestone has passed acceptance and been locked in: this is a “routine clearing” — after every key structural milestone is locked in, save verified state into documentation before clearing the session;
5. The session has grown very long: a turn threshold, such as the teaching example of 50–100, prompts inspection rather than proving failure. Consider budget use, irrelevant material, and repeated missed constraints before rebuilding.

14.2 The “Three-Stage” Context Rebuild Method: Identity Injection → State Restoration → Action Directive

Resetting the context never means losing progress. The correct approach is: extract from the current engineering workspace the latest and correct core interface definitions, the database structure contract, and the list of next-step (Next Step) todos about to be done. Package these pure “effective assets” as a brand-new “implementation blueprint,” and feed them to the AI in a completely fresh, empty conversation window.

The essence of this practice is to completely sever the AI’s “negative historical memory.” You are, in effect, dismissing an exhausted old implementation crew whose heads are full of tangled logic, then taking a carefully organized, crystal-clear set of latest blueprints and hiring a fresh implementation crew — clear-headed and highly focused — who pick up directly from the sturdiest current step and keep building upward.

The concrete operation of the “three-stage” context rebuild method:

Example type: reference. Reference fragment; it is not guaranteed to run alone. Adapt it to the lesson context, project versions and real interfaces, then validate with observed output.

Stage 1: Identity injection (who I am and what the project is)
"Read @CONTEXT.md in the project root. Understand the system's architectural
specification, the locked-in nodes that must not be changed (completed milestones),
and the current implementation progress.
Also read .docs/AGENTS.md and .docs/ARCHITECTURE.md for behavior duties and red lines."

Stage 2: State restoration (where we are and where to resume)
"According to the latest CHANGELOG.md entry and job.progress.md, we are in
Phase 2 and have just completed milestone 2.2 (order creation)."

Stage 3: Action directive (what to do next and how)
"Once you understand, proceed to the Next Step plan (milestone 2.3, order details)
and explain your implementation approach. Present the plan first and wait for
confirmation before coding."

Context injection supplies material for realignment; it does not guarantee instant or perfect handover. Have AI restate the goal, applicable red lines, verified state, and next step, then check them against documents and the actual workspace. Fill gaps and resolve conflicts before continuing authorized work.

14.3 Avoid Turning the Session into a “Garbage Dump”

Even without triggering the clearing criteria, you can control information quality in your day-to-day interactions and keep the session from rotting prematurely:

1. Save conclusions before managing history: record verified facts and reasons for abandoning approaches. Saying “forget the past” does not guarantee history removal. Use supported clear or compaction features and check the retained material;
2. Important information goes into documents, not conversations: any important decision, core rule, or milestone result should be captured in the project documentation at the first moment, rather than existing only in the conversation context;
3. Call a timely stop to “meaningless debates”: you are talking to a machine with no emotions and nothing but probability computations. Arguing will not trigger its “sudden enlightenment”; it will only fill the current conversation window with more erroneous logic and garbage context. When AI goes in circles, stop ineffective attempts, save verified state, then rebuild context; decide separately under Chapter 10 whether code needs rebuilding;
4. “De-noise” your instructions: do not pile irrelevant context and historical background into your instructions. The cleaner the information you give the AI, the more focused its attention.

Remember: conversation history is not your asset — it is your liability. Abandon any fantasy about conversation history, and let documentation become the sole, eternal, unshakable “single source of truth” between you and the AI.

[Operation Card] Four Steps for a Rapid Restart After /clear

Purpose: make “clearing the session” a zero-stress, anytime-available action rather than a decision requiring psychological preparation.

Example type: reference. Reference fragment; it is not guaranteed to run alone. Adapt it to the lesson context, project versions and real interfaces, then validate with observed output.

1. Confirm that the documents are up to date
   □ CONTEXT.md (blueprint): does the architecture match the current code?
   □ CHANGELOG.md (ship's log): is today's progress recorded?
   □ job.progress.md / TODO list: is the next task clear?
   If not, spend two minutes updating them first. This is the safety prerequisite
   for clearing the session.

2. Use the tool-supported /clear (Claude Code is the example)
   Confirm step 1 is complete before clearing the current session.
   A natural-language instruction to forget is not a clear operation.

3. Rebuild in three stages
   First message in the new session:
   "Read @CONTEXT.md, @.docs/AGENTS.md, @.docs/ARCHITECTURE.md,
    and @.docs/CHANGELOG.md to understand current facts, constraints, and progress. We are at milestone X; next is Y. Explain your implementation
    approach first and wait for confirmation before starting."

4. Verify the AI's understanding
   Ask the AI to restate the current architecture, locked-in nodes, and next task.
   If it understands correctly, let it start; if it has gone off track, correct it
   before continuing. Once confirmed, authorize it with a brief instruction,
   such as "Start."

See Claude Code best practices for tool behavior: /clear resets context, and compaction may also be available. Saving, restating, and verifying are this book’s operational discipline; the clear command does not guarantee quality.

Finally, remember that line from Section 14.1, repeatedly borne out in practice: clearing the session is not “giving up progress” — it is “taking the latest blueprints and continuing to build upward from the sturdiest step.”

---

Part Four is complete. You have now mastered the methods for framing the AI with documents and boundaries: requirements analysis (Event Storming, REQUIREMENTS.md, and the divergence log), blueprint design (the seven sections and four principles of CONTEXT.md), effective constraints (the three-pillar documents, negative-space design, the five principles of constraint directives, and modular decoupling), and context management (the five hard clearing criteria and the three-stage rebuild method).

Now, let us enter Part Five: The Skill System — Collaboration and Selection Across 14 Skills. You will see how a complete AI coding team operates like a construction crew with a clear division of labor.

Independent exercise

Use fictional or authorized deidentified material. Answer independently before revealing the reference. Save chapter-14.md with versions, decisions, evidence and gaps.

Prepare a handoff with role and constraints, verified state and next task. List three claims that need repository or log verification.

Required chapter artifact: three-part context rebuild pack

The submission for this independent exercise must contain the evidence below. The existing prompts supply content but do not replace these acceptance items.

• O1: The three-part context rebuild pack draws both a forward path and a return path across state capture, context reset and constraint rebuild
• O2: Every stage in the three-part context rebuild pack states its input, decision, output and owner
• O3: The artifact contains pre-reset state, rebuild inputs and a post-reset difference check

Reveal reference feedback (answer first)

Reference feedback

Verify branch, file diff and check logs. Retain authorization and safety boundaries and list unfinished work and failures. Clearing a session does not clear files, reset permissions or guarantee forgetting. A previous assistant’s ‘passed’ is not an inspection record.

Self-review and next steps

Check whether your decision is explicit, evidence reproducible and unknowns honestly recorded. The reference illustrates one defensible approach, not a unique answer. Seek peer review for alternatives with equivalent evidence. Mark unsupported parts unfinished and revisit the corresponding step.