L4Lesson 5

Checkpoint and Clear

After this, you'll be able to use /clear and session checkpoints as a deliberate workflow rhythm, not just a panic button when things go wrong.

Before you start

Complete Trust No Retrieved Document first; this lesson builds on trust discipline so that the clean context you start after a /clear is actually clean rather than carrying over poisoned content.

The idea

Here is the before and after: It is 6pm. You finished the auth feature. The session is 47 turns long and you know the next thing to build. You could just start typing. But those 47 turns are still in context, including three false starts, two corrected wrong answers, and a tangent about a bug you already fixed. The next answer will be shaped by all of that. The right move is not to keep going. It is to checkpoint and clear.

Most people use /clear when they are frustrated. The session broke, the model is confused, nothing is working. That is exactly the wrong time to reach for it.

/clear should happen when you finish a phase of work, not when you hit a wall. Think of it the way you think of a git commit: you commit when you have something that works, not when everything is on fire. Before you /clear, you checkpoint: you write down (in a file, or by asking Claude to summarize) what you accomplished, what decisions you made, and what the next session needs to know. Then you /clear. The next session starts clean, with only the checkpoint in context, rather than 47 turns of accumulated history that may include contradictions, stale state, and context poisoning.

Here is the practical rhythm used by engineers who run long Claude Code sessions: finish a feature or a phase, ask Claude to write a one-paragraph session summary to a project-state.md file, then /clear. The next session opens with a single read of project-state.md and Claude is immediately current, with a clean context and no accumulated noise.

Try it (15 min)

Watch out for

Using /clear when something breaks. Diagnose first. /clear destroys the context that would help you debug.
Clearing without a checkpoint. You will spend the next session rebuilding context you already had.
Checkpoints that list tasks instead of state. 'We added auth' is less useful than 'Auth is complete. The next step is connecting it to the user profile endpoint at /api/users/:id.'
One permanent mega-session. Sessions have an effective attention span. Past 30-40 turns, coherence degrades even before you hit the token ceiling.

Paste this into Claude:

I am about to end a phase of my current work and use /clear. Before I do, help me write a checkpoint. Summarize: (1) What we accomplished in this session, (2) Any decisions we made that the next session needs to know, (3) The current state of the project (what is done, what is in progress, what is blocked), (4) The exact next step for the next session to pick up from. Format it as a short project-state.md I can paste at the start of the next session.

What good looks like:

You produced a project-state.md that a fresh session could read and immediately resume from
The checkpoint captures decisions, not just a list of tasks completed
You used /clear after saving the checkpoint, not instead of making one
The next session you started, you opened with the checkpoint and did not re-explain context you had documented
The fresh session's first output was more focused than the last few outputs of the previous session

What a good response looks like:

Here is your project-state.md for this session.

```markdown
# Session checkpoint, auth feature complete

## What we accomplished
Implemented JWT authentication end-to-end. Login endpoint returns a signed token. The requireAuth middleware validates it on protected routes. Refresh token logic is in src/services/auth.ts.

## Decisions made
- Tokens expire in 15 minutes (not 1 hour as originally planned). Chose shorter expiry after discussing the security tradeoff.
- Refresh tokens are stored in httpOnly cookies, not localStorage. This was a deliberate choice to prevent XSS access.
- We did NOT implement token revocation. Logged as a known gap. Out of scope for this sprint.

## Current state
Done: login, token validation, refresh flow, requireAuth middleware.
In progress: nothing.
Blocked: nothing.

## Next session start here
Next task: add the user profile endpoint at GET /api/users/:id. It should use requireAuth middleware and return the user object minus the password hash. Start with @src/middleware/requireAuth.ts and @src/models/User.ts already loaded.
```

Start your next session by pasting this file. You will be current in 10 seconds instead of 10 minutes.

When this breaks

Breaks when /clear is used as a debugging tool because the context that would explain the failure is exactly what gets destroyed and you lose your only diagnostic surface.
Breaks when the checkpoint is a task list rather than a state description because the next session knows what was done but not where to resume or which decisions are now load-bearing.
Breaks when long-running narrative or research work is forced into hard phase boundaries because clean cuts that work for code phases destroy the implicit threads a multi-day investigation depends on.

Claude can do it for you

At the end of any session, say: 'Write a project-state.md for this session. Include what we built, decisions we made, current state, and the exact next step.' Save it, then /clear. The next session opens with that file and nothing else.

You can now

Produce a project-state.md from your current session that captures decisions, current state, and the exact next step, then resume in a fresh session using only that file.

Key takeaways

Checkpoint, then clear, in that order, every time. Fresh context per work unit is the workflow, not a workaround.

/clear is a phase boundary like a git commit, not a panic button when things break.
Checkpoint before you clear. The checkpoint is what makes the next session productive in 10 seconds.
Capture decisions, not tasks. State and rationale outlive the to-do list.
Mega-sessions degrade past about 30-40 turns even before the token ceiling.
The next session opens with the checkpoint file and nothing else. That is the rhythm.

Go deeper

I am about to end a phase of my current work and use /clear. Before I do, help me write a checkpoint. Summarize: (1) What we accomplished in this session, (2) Any decisions we made that the next session needs to know, (3) The current state of the project (what is done, what is in progress, what is blocked), (4) The exact next step for the next session to pick up from. Format it as a short project-state.md I can paste at the start of the next session.

Here is your project-state.md for this session. ```markdown # Session checkpoint, auth feature complete ## What we accomplished Implemented JWT authentication end-to-end. Login endpoint returns a signed token. The requireAuth middleware validates it on protected routes. Refresh token logic is in src/services/auth.ts. ## Decisions made - Tokens expire in 15 minutes (not 1 hour as originally planned). Chose shorter expiry after discussing the security tradeoff. - Refresh tokens are stored in httpOnly cookies, not localStorage. This was a deliberate choice to prevent XSS access. - We did NOT implement token revocation. Logged as a known gap. Out of scope for this sprint. ## Current state Done: login, token validation, refresh flow, requireAuth middleware. In progress: nothing. Blocked: nothing. ## Next session start here Next task: add the user profile endpoint at GET /api/users/:id. It should use requireAuth middleware and return the user object minus the password hash. Start with @src/middleware/requireAuth.ts and @src/models/User.ts already loaded. ``` Start your next session by pasting this file. You will be current in 10 seconds instead of 10 minutes.

At the end of any session, say: 'Write a project-state.md for this session. Include what we built, decisions we made, current state, and the exact next step.' Save it, then /clear. The next session opens with that file and nothing else.