/context-management

name: context-management
description: >
  Use in long or noisy sessions to persist durable state across session
  boundaries via state.md. Also generates project-map.md when asked to map
  the project. Triggers on: user explicitly asks to "save state", "compress
  context", "map this project", "generate project map", "create project map",
  cross-session handoff needed, or repeated failures indicate context is
  getting stale.

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](#project-map) section | | "save state" / "compress context" / session ending with ongoing work | [Procedure](#procedure) 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 "<keyword1>" session-log.md | tail -20
grep -i "<keyword2>" session-log.md | tail -20

Check the hit count before reading results. This tells you whether to narrow or widen before committing to any output.

**Step 3 — Adjust based on hit count:**

• **0 hits on all keywords** → fall back to `project-map.md` Critical Constraints. Relevant history may have been promoted there instead of staying in the log. If still nothing, proceed without history.
• **1–10 hits** → read them. Surface past decisions, rejected approaches, and constraints.
• **>10 hits on one keyword** → narrow with a second term: `grep -i "<kw1>" session-log.md | grep -i "<kw2>" | tail -20`

**Step 4 — Surface what matters.** If relevant entries are found, state them explicitly before proceeding: what was decided, what was rejected, what constraints apply. Don't silently absorb them — make them visible so the user can confirm or override.

When saving state (explicit invocation)

1. Extract durable artifacts only:

• Approved design decisions
• Active plan tasks and their status
• Verified facts/evidence
• Open questions/risks

**state.md vs plan.md:**

• `plan.md` (or `docs/.../plans/*.md`): the authoritative task list with checkboxes. Owned by `executing-plans`. Updated as tasks complete.
• `state.md`: a session-boundary snapshot of *where you are* in the plan — current task, blockers, what's verified. It references the plan but does not duplicate the task list.

If a plan exists, state.md should say "Executing plan at docs/.../plan.md, currently on Task 3" — not copy the full task list.

2. Write `state.md` at the project root with concise sections:

• `Current Goal`
• `Decisions`
• `Plan Status`
• `Evidence`
• `Open Issues`

3. **Check for superseded entries before appending.** Grep `session-log.md` for 2-3 keywords from the current decision:

   grep -i "<keyword>" session-log.md

Read any matching `[saved]` entries and ask: does the new decision *directly contradict* an old one? If yes, append `[superseded by YYYY-MM-DD]` to the old entry's header line — do not delete it. If the old entry is merely related but not contradicted, leave it unchanged. This is a judgment call, not a mechanical keyword match.

4. Append a `[saved]` entry to `session-log.md`:

**What belongs here vs state.md:**

• `session-log.md [saved]`: permanent decisions, anti-patterns to avoid, carry-forward open items
• `state.md`: active task status, in-progress plans, checklists, version bump readiness — anything that will be resolved soon

**Never include in a [saved] entry:**

• Test results or verification confirmations ("11/11 tests pass")
• Task checklists, file changelogs, or release notes → use `state.md`
• "How it works" walkthroughs → read the code
• Speculative analysis not approved for implementation → use a design doc in `docs/`
• One-time confirmations ("file deleted", "folder removed")
• Newly discovered permanent architectural constraints → add to `project-map.md` Critical Constraints instead

**Hard limits per component — enforce while writing, not after:**

• Goal: 1 line, ≤15 words
• Decisions: ≤5 bullets for multi-subsystem sessions, ≤3 for single-topic. Each bullet: decision + one-sentence why, ≤25 words total. No prose, no rationale beyond the why.
• Rejected: ≤3 bullets, ≤15 words each. What to avoid — not the full story of why it failed.
• Open: ≤2 items, ≤12 words each.

If a decision doesn't fit in 25 words, the explanation belongs in a design doc. Cut the explanation, not the decision.

Total entry backstop: 250 words / 1500 chars. If exceeded, a bullet violated its limit — find it and cut it. Typical single-topic sessions should targe