Context Lifecycle: Document, Clear, Resume

intermediate 12 min 📋 Copy-paste ready

Sources not yet verified

contextclearworkflowphasespower-user

Scenario

Context: You're working on a complex task and notice the AI's responses are degrading in quality

Goal: Learn the Document & Clear pattern and phased workflow for maintaining high-quality AI output

Anti-pattern: Letting context accumulate until quality degrades, trusting auto-compaction

Tools: Claude CodeGitHub CopilotCursor

Conversation

The Context Lifecycle Problem

AI context windows have limits. As conversation grows:

• Older context gets compressed or dropped
• Quality degrades as relevant info is lost
• Auto-compaction is unpredictable

Solution: The Document & Clear Pattern

1. Document: Save important state to external files
2. Clear: Explicitly reset context with /clear
3. Resume: Start fresh by reading the saved files

Tool Support:

• Claude Code: /clear command
• GitHub Copilot: /clear command (same!)
• Cursor: New Composer session

Both Claude Code and Copilot CLI now share the same /clear command. The tools have converged.

When to Clear Context

Rule of thumb: If less than 50% of prior context is relevant to current work, clear it.

Symptoms of context bloat:

• AI forgets earlier decisions
• Responses become inconsistent
• AI asks questions you already answered
• Quality noticeably drops

👤 You

Before I clear, let me document the current state.

Please write a progress summary to docs/refactor-progress.md including:

1. What we've completed
2. Key decisions we made
3. Current blockers
4. Next steps

Capture state BEFORE clearing. This creates durable external memory.

🤖 AI

I'll create a progress summary:

# Refactor Progress - Auth System

## Completed
- [x] JWT service implementation (`src/services/jwt.ts`)
- [x] Refresh token rotation logic
- [x] Database migration for refresh_tokens table
- [x] Type definitions (`src/types/auth.ts`)

## Key Decisions
- Access token expiry: 15 minutes
- Refresh token expiry: 7 days  
- Refresh rotation: Single-use (invalidate on use)
- Backward compatibility: Dual-mode auth during migration

## Current Blockers
- Need to decide on token storage (httpOnly cookie vs localStorage)
- Rate limiting strategy for refresh endpoint

## Next Steps
1. Create hybrid auth middleware (accepts session OR JWT)
2. Update `/auth/login` to return tokens
3. Add `/auth/refresh` endpoint
4. Update frontend auth hook

Written to docs/refactor-progress.md.

This file now contains everything needed to resume. It's in version control and won't be lost.

👤 You

/clear

Clear the context explicitly. Fresh start with no accumulated noise.

🤖 AI

Context cleared. Ready for a fresh start.

Context is now empty. The AI has no memory of previous conversation.

👤 You

Read docs/refactor-progress.md and continue with the next steps. Start with the hybrid auth middleware.

Resume by reading the file. The AI gets only the relevant context, nothing stale.

🤖 AI

Reading docs/refactor-progress.md...

Got it. You're migrating from session-based auth to JWT. The JWT service is complete. Now I'll create the hybrid auth middleware that accepts both session AND JWT during the migration period.

// src/middleware/hybridAuth.ts
import { Request, Response, NextFunction } from 'express';
import { verifyAccessToken } from '../services/jwt';
import { getSession } from '../services/session';

export async function hybridAuth(req: Request, res: Response, next: NextFunction) {
  // Try JWT first (preferred path)
  const authHeader = req.headers.authorization;
  if (authHeader?.startsWith('Bearer ')) {
    const token = authHeader.slice(7);
    try {
      req.user = await verifyAccessToken(token);
      req.authMethod = 'jwt';
      return next();
    } catch (e) {
      // Fall through to session check
    }
  }
  
  // Fallback to session (legacy path)
  const session = await getSession(req);
  if (session?.userId) {
    req.user = { id: session.userId };
    req.authMethod = 'session';
    console.warn('DEPRECATION: Session auth used. Migrate to JWT.');
    return next();
  }
  
  return res.status(401).json({ error: 'Authentication required' });
}

Created hybrid middleware. What's next?

Fresh context = focused, high-quality output. The AI picked up exactly where you left off.

---

The Research → Plan → Implement Workflow

For complex tasks, use a phased approach with context clearing between phases:

1. Research Phase: Explore codebase, understand patterns
2. /clear - Reset context
3. Plan Phase: Create detailed implementation plan
4. /clear - Reset context
5. Implement Phase: Execute the plan with focused context

Key insight: Reviewing the plan is higher leverage than reviewing the code.

👤 You

RESEARCH PHASE

Explore how authentication is handled across the codebase. Find:

1. All auth-related files
2. Existing patterns and conventions
3. Dependencies and integrations

Don't write any code yet - just research and write findings to docs/auth-research.md.

Explicit instruction to research only AND write to file. The file is durable memory that survives /clear.

🤖 AI

I'll research the auth landscape and document findings...

# Auth System Research

## Files Found
- `src/middleware/auth.ts` - Current session-based middleware
- `src/services/session.ts` - Redis session management
- `src/routes/auth.ts` - Login/logout/register endpoints
- `src/hooks/useAuth.ts` - Frontend auth hook (React Query)
- `tests/auth/**` - 45 auth-related tests

## Patterns Observed
- All protected routes use `authMiddleware`
- Session stored in Redis with 24h TTL
- Frontend uses `useAuth().user` for current user
- API errors use `{ error: string, code?: string }` format

## Dependencies
- express-session (v1.18.0)
- connect-redis (v7.1.0)  
- Frontend: @tanstack/react-query for auth state

## Integrations
- User service fetches profile on auth
- Websocket auth uses same session cookie
- Admin dashboard has separate auth check

Written to docs/auth-research.md. Ready for planning phase when you are.

Research written to file. This persists after /clear - the key to the Document & Clear pattern.

👤 You

/clear

Clear before planning. Research phase might have accumulated irrelevant exploration.

🤖 AI

Context cleared.

Ready for focused planning with clean slate.

👤 You

PLAN PHASE

Read docs/auth-research.md and create a detailed implementation plan for JWT migration that:

1. Maintains backward compatibility
2. Handles all integrations found
3. Includes test strategy

Write the plan to docs/jwt-migration-plan.md.

Planning phase reads from research file. Explicit file reference - no ambiguity about what to read.

🤖 AI

Reading docs/auth-research.md... Creating implementation plan:

# JWT Migration Plan

## Phase 1: Infrastructure (No Breaking Changes)
1. Add JWT service (sign, verify, refresh)
2. Add refresh_tokens table
3. Create hybrid auth middleware
4. All existing code continues to work

## Phase 2: Dual-Mode Operation
1. Update `/auth/login` to return JWT + session
2. Add `/auth/refresh` endpoint
3. Update websocket to accept JWT auth
4. Frontend: Add JWT support to useAuth (opt-in flag)

## Phase 3: Migration Period (2 weeks)
1. Log usage: track session vs JWT auth
2. Notify clients via deprecation header
3. Update admin dashboard
4. All new features use JWT-first

## Phase 4: Session Removal
1. Remove session fallback from hybrid middleware
2. Remove Redis session store
3. Remove express-session dependency
4. Update documentation

## Test Strategy
- Unit: JWT service (sign, verify, rotate)
- Integration: Hybrid middleware (both paths)
- E2E: Full login → refresh → logout flow
- Regression: All 45 existing auth tests must pass

## Risks & Mitigations
- Risk: Client not migrating → Mitigation: 2-week deprecation period with warnings
- Risk: Websocket auth breaks → Mitigation: Test in staging first

Plan written to docs/jwt-migration-plan.md.

Review this plan before implementation. Catching issues here is much cheaper than catching them in code.

The plan is now a reviewable artifact. Review at this stage has maximum leverage.

---

Context Utilization Target

Keep context utilization at 40-60%:

• Below 40%: You might be clearing too often
• Above 60%: Quality may start degrading
• Above 80%: Clear immediately

Most AI tools show context usage. Monitor it and clear proactively.

Key Takeaways

• Use `/clear` to reset context when <50% remains relevant (works in both Claude Code and Copilot)
• Document state to external files BEFORE clearing - create durable memory
• Research → Plan → Implement: Clear context between phases for focused work
• Review the plan before implementation - highest leverage review point
• Keep context utilization at 40-60% for optimal quality

Try It Yourself

Prompt Template

Before clearing, summarize current progress to a markdown file:

Please write a progress summary to `docs/progress.md` with:
1. What's completed
2. Key decisions made
3. Next steps

Then I'll use /clear to reset context.

Copy template

Variations to Try

• Simple clear: Just use `/clear` for a fresh start
• Research phase: "Explore the codebase for [topic]. Don't write code yet - just document findings."
• Plan phase: "Read [research file] and create an implementation plan in [plan file]."
• Resume: "Read [progress file] and continue with the next steps."

Related Content

📖 Context Windows 📖 Tokens & Tokenization 🏋️ context management

Sources

✓ Shrivu Shankar: Document & Clear Method ⓘ

×

How I Use Every Claude Code Feature

Introduces the Document & Clear pattern for managing AI context. Key insight: rather than trusting automatic context compaction, explicitly clear context and persist important state to external files. This produces more reliable outputs and gives you control over what the AI 'remembers'.

Key Findings:

• Document & Clear method: dump plan to .md file, /clear, restart with file reference
• Auto-compaction is opaque, error-prone, and not well-optimized - avoid /compact
• Use /clear + /catchup for simple reboots (custom command reads uncommitted changes)

Credibility: high

Referenced by:

Document & Clear Pattern Context Lifecycle: Document, Clear, Resume

View Source ↗

✓ HumanLayer: Phased Workflow ⓘ

×

Advanced Context Engineering for Coding Agents

HumanLayer

Introduces the Research → Plan → Implement workflow for AI-assisted development. Key insight: reviewing plans is higher leverage than reviewing code. The workflow explicitly clears context between phases to maintain focus and quality.

Key Findings:

• Research → Plan → Implement workflow produces better results than direct coding
• Keep context utilization in the 40-60% range depending on complexity
• A bad line of a plan could lead to hundreds of bad lines of code - review plans first

Credibility: high

Referenced by:

Agentic Loops Document & Clear Pattern TDD for AI Agents Context Lifecycle: Document, Clear, Resume

View Source ↗