Stats
Actions
Tags
From austinpowers
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/austinpowers:context-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
| User said | Go to |
| 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 |
| 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.
Claude Code automatically compresses context within a session. This skill has two complementary responsibilities:
state.md preserves decisions and progress for the current task when a session ends mid-work.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.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:
project-map.md Critical Constraints. Relevant history may have been promoted there instead of staying in the log. If still nothing, proceed without history.grep -i "<kw1>" session-log.md | grep -i "<kw2>" | tail -20Step 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.
Extract durable artifacts only:
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.
Write state.md at the project root with concise sections:
Current GoalDecisionsPlan StatusEvidenceOpen IssuesCheck 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.
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 itemsstate.md: active task status, in-progress plans, checklists, version bump readiness — anything that will be resolved soonNever include in a [saved] entry:
state.mddocs/project-map.md Critical Constraints insteadHard limits per component — enforce while writing, not after:
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 target ~120 words; the higher cap exists for multi-subsystem sessions that genuinely touched 5+ areas.
## YYYY-MM-DD HH:MM [saved]
Goal: <one line>
Decisions:
- <what was chosen and the one-sentence why — not how it works>
Rejected: <what NOT to try, one line each — the anti-pattern knowledge>
Open: <carry-forward items only>
After appending the [saved] entry, update the stop-hook marker so the decision-log reminder resets:
node -e "require('fs').writeFileSync(require('path').join(process.env.HOME||process.env.USERPROFILE||'.', '.claude','hooks-logs','last-saved-entry.txt'), new Date().toISOString())"
This prevents the stop hook from re-firing the decision-log reminder on every subsequent stop in the same session.
In a new session, read state.md first to restore task context, then grep session-log.md for relevant history.
The log contains a single entry type:
File management:
CLAUDE.md and package.json[superseded by YYYY-MM-DD]For cross-project recall (finding how a similar problem was solved in a different codebase): session-log.md is per-project and keyword-searchable only. Cross-project recall is outside the scope of this system.
project-map.md is the semantic memory layer — it captures the project's structure, key file purposes, and critical non-obvious constraints so that future sessions can orient without re-globbing or re-reading known files. Generate it once; update it when the project changes.
Check for git:
git rev-parse --git-dir 2>/dev/null
git rev-parse HEAD as the staleness hash.git init? It enables precise staleness tracking for project-map.md — creates a .git folder, touches none of your files. If you'd prefer not to, I'll fall back to file timestamp comparison instead, which works fine but is slightly less precise."
git init --quiet, then proceed with git hash.Map the structure: Glob the project, identify the top-level directories and their purpose. Do not enumerate every file — summarise by directory.
Document key files: For each file that is load-bearing, non-obvious, or frequently referenced, write one line describing what it does and why it matters. Aim for 10–20 entries. Skip files whose purpose is obvious from their name.
Capture critical constraints: The highest-value section. These are non-obvious facts that are not visible in the code itself — quoting rules, platform differences, version sync requirements, things that caused bugs before. Pull these from session-log.md [saved] entries and from known-issues.md if they exist.
Identify hot files: From session-log.md history, list the files most frequently appearing in Files: lines. These are the ones most likely to need freshness checks on future sessions.
Write project-map.md at the project root — same level as CLAUDE.md and package.json, never in docs/ or any subdirectory. The session-start hook looks for it with ls project-map.md 2>/dev/null from the project root — if it's anywhere else, the hook cannot find it and every future session loses the map. Use this format:
# Project Map
_Generated: YYYY-MM-DD HH:MM | Git: <short-hash> | (or: Staleness: timestamps)_
## Directory Structure
<dir>/ — <one-line purpose>
<dir>/ — <one-line purpose>
## Key Files
<path> — <what it does and why it matters>
<path> — <what it does and why it matters>
## Critical Constraints
- <non-obvious fact that would cost time to rediscover>
- <non-obvious fact that would cost time to rediscover>
## Hot Files
<path>, <path>, <path>
When the staleness check in the entry sequence flags changed files:
Keep project-map.md under 150 lines. If it grows beyond that, it is not a map — it is documentation. Prune file entries for things that are now obvious from context.
Open Issues.state.md under 100 lines — if it's longer, it's not compressed enough.npx claudepluginhub daltonworsnup/austinpowers --plugin austinpowersGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.