dwsy/context-management

Context Management

CRITICAL: THIS SKILL MANAGES YOUR MEMORY. WITHOUT IT, YOU WILL FORGET.

Your context window is limited. As conversations grow, "pollution" (noise, failed attempts) degrades your reasoning.

YOU MUST PROACTIVELY MANAGE YOUR HISTORY. Do not wait for the user to tell you.

The Core Philosophy: Build, Perceive, Navigate

Context Window = RAM (Expensive, volatile, limited)
Context Graph  = Disk (Cheap, persistent, unlimited)

→ Move finished tasks from RAM to the Graph.

Manage your context window like a Git repository. You are the maintainer.

1. BUILD the Skeleton (context_tag):
   • Raw conversation is a flat list. Tags create structure.
   • Without tags, context_log is just a list of IDs. With tags, it is a Map.
2. PERCEIVE the State (context_log):
   • Check the HUD: Is "Segment Size" too big? You are drifting.
   • Check the Graph: Where are you? Are you in a deep branch?
3. NAVIGATE & MERGE (context_checkout):
   • Squash: Convert a messy "feature branch" (thinking process) into a single "merge commit" (summary).
   • Jump: Move between tasks or retry paths without carrying baggage.

Quick Start: The Loop

Follow this cycle for every major task:

1. CHECK: Verify state. context_log
2. START: Tag the beginning with a semantic name. context_tag({ name: "<task-slug>-start" }) // e.g., auth-login-start
3. WORK: Execute steps.
4. MILESTONE: Tag intermediate stable states. context_tag({ name: "<task-slug>-plan" }) // e.g., auth-login-plan
5. SQUASH (Autonomous): If history becomes noisy or low-density, Squash with Backup.
   • Action: context_checkout({ target: "<task-slug>-start", message: "...", backupTag: "<task-slug>-raw-history" })
   • Action (Optional): context_tag({ name: "<task-slug>-done" })
   • Safety: If you need the details later, checkout the backup tag.

Tool Reference

| Tool | Analog | Purpose | When to Use | | :--- | :--- | :--- | :--- | | context_tag | git tag | Bookmark a stable state. | Before risky changes. Before starting a new task. | | context_log | git log | See where you are. | When you feel lost. To find IDs for checkout. | | context_checkout| git reset --soft | Time Travel / Squash. | To undo mistakes. To compress history. |

Critical Rules

Tag Wisely (Build The Skeleton)

Tags are the "Table of Contents". Name them so you can understand the history at a glance.

Naming Formula: <task-slug>-<phase>

• task-slug: Short, kebab-case identifier for the task (e.g., auth-login, db-migration)
• phase: The stage of work (start, plan, impl, done, fail, backup)

| Bad (Generic) | Good (Semantic) | Why | | :--- | :--- | :--- | | task-start | auth-oauth-start | Describes WHAT task | | pre-research | error-log-analysis-start | Future-you knows the topic | | phase-1-done | db-schema-plan-done | Know which phase of which task | | debug-retry | null-pointer-fix-retry | What bug? |

Tag Categories:

| Category | Pattern | Examples | | :--- | :--- | :--- | | Start | <task>-start | auth-jwt-start, docker-setup-start | | Plan | <task>-plan | api-v2-plan, migration-plan | | Milestone | <task>-<milestone> | auth-jwt-impl-done, tests-passed | | Backup | <task>-raw-history | auth-jwt-raw-history | | Failure | <task>-fail-<reason> | auth-jwt-fail-timeout |

How to generate: Ask yourself "What is the task?" → Extract 1-3 keywords (e.g., "fix login timeout" → login-timeout-fix-start)

Squash Noise, Keep Signal, Focus on Goal (Context Hygiene)

Think of your conversation as a "Feature Branch" full of messy thoughts. You must distinguish Signal from Noise.

• Signal (High Value): Design decisions, user constraints, final working code. -> KEEP.
• Noise (Low Value): Failed attempts, long tool outputs, "thinking" steps. -> SQUASH.
• Focus on Goal: Ask yourself: "Does this message help me achieve the current goal?" -> KEEP.

When to Squash:

1. Task Done: Convert the messy process into one clean summary.
2. Low Density: You read 2000 lines but only found 1 error.

Safety: Squashing is LOSSLESS. By using backupTag, you save the "Messy Branch" forever. You can always checkout the backup tag if the summary isn't enough.

• Main Trunk: Jump back to the summary.
• Backup Tag: Jump back to the raw details.

Fail Fast, Revert Faster

If you fail 3 times:

1. STOP. Don't try a 4th time.
2. context_checkout back to the last safe tag.
3. Summarize the failure in the checkout message ("Tried X, failed because Y").
4. Try a new approach from the clean state.

After Checkout: Execute Next Step

When context_checkout completes and injects a summary, you are in a new context.

1. READ the injected summary carefully
2. EXECUTE the Next Step from the summary - this is your new task.

Decision Matrix: When to Act

| Situation | Action | Reason | | :--- | :--- | :--- | | Starting Task | context_tag({ name: "<task-slug>-start" }) | Create a rollback point. | | Research / Logs | context_checkout (Squash) | Process is Noise. Read 2000 lines -> Keep result. | | Messy Debugging | Squash w/ Backup | Cleanup. The error logs are noise once fixed. | | Task Done (Candidate)| Squash w/ Backup | Assume Success. Summary is usually enough. Backup exists if not. | | Goal Shift | context_checkout (Squash) | Old context is irrelevant. | | Drift (some steps w/o tag) | Tag (Milestone) | Maintain the skeleton. Don't fly blind. |

The "Context Health" Check

If you cannot answer these, run context_log:

| Question | Answer Source | | :--- | :--- | | Where is the skeleton? | The sequence of tags in the log. | | Is this history useful? | If "No" -> SQUASH IT. | | Am I in a loop? | Repeated entries in the graph. |

Good Checkout Messages

The message is your lifeline to your past self. A good message preserves critical context that would otherwise be lost.

Structure: [Key Finding/Status] + [Reason] + [Important Changes] + [Next Step]

• Key Finding/Status: What did you discover or complete? Include specific numbers, errors, or outcomes.
• Reason: Why are you branching/moving? (e.g., "Task complete", "Approach failed", "Need raw logs")
• Important Changes: What files or logic have been modified? (This checkout only resets conversation history, NOT disk files, so you must remember what changed.)
• Next Step: What should you do immediately after this squash? Be specific. (e.g., "Wait for user feedback", "Implement the recommended fix", "Revert file X and try approach Y")

Examples:

• Good (Resetting after failure): "Recursive parser hit stack overflow at depth 8000. Switching to iterative. Reason: Stack limit reached. Important Changes: Modified utils/recursion.ts. Next Step: Inform user of the failure and propose iterative approach."
• Good (Cleaning up): "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. Reason: Task done, cleaning context. Important Changes: Created auth/, modified routes.ts and middleware.ts. Next Step: Report completion to user, ask if they want to review or test."
• Bad: "Switching context." (Too vague - you will forget why)
• Bad: "Done." (What is done? What should you do next?)

Anti-Patterns

| Don't | Do Instead | | :--- | :--- | | Blind Tagging (Tagging without looking) | Check (context_log) to avoid duplicates or tagging noise. | | Over-Tagging (Tagging every step) | Tag only major phase changes (start, milestone). | | Hoard (Keep all history "just in case") | Squash low-density history (research, logs). | | Panic (Apologize repeatedly for errors) | Revert (context_checkout) to before the error. | | Blind Checkout (Guessing IDs) | Look (context_log) first to get valid IDs. | | Vague Summaries ("Done", "Fixed") | Detailed Summaries ("Found bug in line 40. Fixed with patch X.") | | Generic Tag Names (task-start, phase-1) | Semantic Names (auth-jwt-start, db-schema-plan) | | Missing Next Step in checkout message | Always specify what to do after squash (e.g., "Wait for user", "Implement fix X") |

Recipes (Copy-Paste)

1. The "Miner" (Immediate Squash)

Goal: Pure information gathering (Reading files, Searching web). Why: The process of searching is irrelevant. Only the result matters.

Example Task: Analyzing error logs to find root cause of timeout

// 1. Tag BEFORE starting the noisy work (use descriptive name)
context_tag({ name: "timeout-analysis-start" });

// ... (Read 5 log files, search 3 docs, find DB connection pool exhaustion) ...

// 2. Squash IMMEDIATELY. Do not wait for user.
context_checkout({
  target: "timeout-analysis-start",
  message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only). **Next Step**: Report findings to user and await approval to implement fix.",
  backupTag: "timeout-analysis-raw-history" // Safety backup
});
context_tag({ name: "timeout-analysis-done" });

2. The "Candidate" (Wait for Confirmation)

Goal: You finished a complex task. Why: The history is noisy. The result is clean. Safety: We create a backup tag automatically.

Example Task: Implementing OAuth login flow

// Squash to Summary (Optimistic Cleanup)
context_checkout({
  target: "oauth-impl-start", // Squash range: Start -> Now
  message: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. **Next Step**: Report completion to user, summarize what was implemented.",
  backupTag: "oauth-impl-raw-history"
});
context_tag({ name: "oauth-impl-candidate" });

3. The "Undo" (Revert Squash)

Goal: User asks about a detail you squashed away. Action: Jump back to the backup tag.

Example Task: Reviewing OAuth implementation details

// Jump back to the raw history
context_checkout({
  target: "oauth-impl-raw-history",
  message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None. **Next Step**: Re-read token refresh implementation and identify the bug."
});
context_tag({ name: "oauth-review-start" });

4. Branching (Alternative Approach)

Scenario: Method A failed (and was squashed). You want to try Method B from the clean state. Action: Checkout the start point.

Example Task: Fixing memory leak - trying different approaches

// Method A (weak references) failed, trying Method B (object pooling)
context_checkout({
  target: "memory-leak-fix-start", 
  message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert). **Next Step**: Revert `CacheManager.ts` changes and implement object pooling strategy."
});
context_tag({ name: "memory-leak-pool-approach-start" });

5. The "Undo" (Failed Attempt)

You tried to fix a bug but broke everything. Goal: Clean up a failed path.

Example Task: Fixing race condition in async handler

// Attempted mutex-based fix, but introduced deadlock
context_checkout({
  target: "race-condition-fix-start",
  message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved). **Next Step**: Revert `AsyncQueue.ts` and implement lock-free compare-and-swap approach.",
  backupTag: "race-condition-mutex-fail" // Save the failure for reference
});
context_tag({ name: "race-condition-lockfree-start" });