context-management

Context Management

Route first — read this before anything else

User said	Go to
"map this project" / "generate project map" / "create project map" / "update project map"	Project Map section
"save state" / "compress context" / session ending with ongoing work	Procedure section
"archive the session log"	session-log.md Format and Maintenance section
Starting a task on a project with existing history	Grep session-log.md first, then proceed

Do not default to state.md for a map request. Do not default to project-map.md for a save-state request.

---

Purpose

Claude Code automatically compresses context within a session. This skill has two complementary responsibilities:

1. Cross-session persistence — state.md preserves decisions and progress for the current task when a session ends mid-work.
2. Accumulated project memory — session-log.md builds a searchable history of decisions, rejected approaches, and hard-won facts across sessions. Written manually via this skill — only when there is something worth preserving.

When to Use

• User explicitly asks to save state or compress context
• Work will continue in a new session and progress must be preserved
• Complex multi-step task has significant accumulated decisions/evidence
• Starting a new task on a project with existing history — grep the log first
• Repeated failures suggest the session has accumulated stale/conflicting context

Procedure

At the start of any non-trivial task

Before diving in, grep session-log.md for history relevant to the current task.

Step 1 — Extract keywords. Take the 2-3 most distinctive nouns from the task description. Avoid generic words ("fix", "update", "file") — use domain nouns ("hook", "auth", "deploy", "staleness").

Step 2 — Grep each keyword individually first:

grep -i -a "<keyword1>" session-log.md | tail -20
grep -i -a "<keyword2>" session-log.md | tail -20

The option -a makes grep read the file as text: without it, the grep of the Claude Code Bash tool prints nothing for a file that holds a byte that is not valid UTF-8 (Unicode Transformation Format, 8-bit). One case remains: the grep of macOS misses a keyword that stands after such a byte on the same line. Check the hit count before reading results. This tells you whether to narrow or widen before committing to any output.