Help close out a coding session by reviewing what changed, updating project docs and agent instructions, and persisting any lessons learned so future sessions start with better context.
The Goal
Two things matter here:
- Keep project docs accurate — if APIs, conventions, or tooling changed during the session, the project's documentation should reflect that.
- Transfer knowledge to future sessions — if something was discovered that would prevent mistakes or save time next session, capture it where future agent instances will read it.
Step 1: Gather Context
Before asking the user anything, build a picture of what happened this session.
Run these to understand recent changes:
git log --oneline -20 # recent commits — focus on this session's work
git diff HEAD~5..HEAD --stat # which files changed across recent commits
git status # any uncommitted changes
Also read any context the user already gave in the current message (they may have called out specific things to capture).
Step 2: Identify Agent Instruction Files
Different projects use different conventions. Scan for whichever exist:
AGENTS.md(Codex/OpenAI convention)CLAUDE.md(Claude Code convention).github/copilot-instructions.md(GitHub Copilot).github/copilot-instructions-*.md(scoped copilot instructions).cursorrulesorcursor.rules(Cursor)- Any file explicitly mentioned in the user's message
Read the ones that exist so you understand their current content and style before proposing additions.
Step 3: Review the Conversation for Corrections
Before looking at git, scan back through the conversation turns of this session and look specifically for moments where the user had to correct or redirect you:
- The user said something was wrong and you had to redo it
- The user overrode a decision you made (e.g., "no, don't do it that way")
- The user had to clarify something you misunderstood, repeatedly
- You made an assumption that turned out to be incorrect
- A tool call or approach failed and the user pointed you toward the right path
For each such moment, ask: could an instruction have prevented this mistake? If yes, that's a strong candidate for the agent instructions. These are the highest-value lessons because they're grounded in actual failure, not speculation.
Note these down — you'll use them in Step 5.
Step 4: Identify What's Worth Capturing
Review both the git changes and your conversation notes with this lens — look for things that would meaningfully change how a future session approaches the project:
Worth capturing in agent instructions:
- New required steps in a workflow (e.g., "always run linting before committing")
- Gotchas or non-obvious constraints discovered (e.g., "this API requires X before calling Y")
- New commands, tasks, or scripts added to the project
- Conventions established during the session (naming, structure, patterns)
- Things that caused mistakes or confusion that instructions could prevent
Worth capturing in project docs (README, etc.):
- New public APIs or changed interfaces
- New setup steps or dependencies
- Changed deployment or build processes
Not worth capturing:
- Implementation details that are obvious from reading the code
- One-off debugging steps specific to a single incident
- Things already documented accurately
Step 5: Ask the User
Present a brief summary combining what you found from git and from the conversation review:
"Here's what I think is worth capturing from this session: [bullet list — include both git-derived changes and any correction moments you spotted]. Is there anything else you want to capture, or anything from this list you'd rather skip?"
Keep it conversational. The user may add things you missed, correct your read of what matters, or say "looks good, go ahead."
Also ask: "Are there any recurring issues or mistakes from past sessions you'd like to capture while we're here?" — this is the opportunity to document known patterns that never got written down, even if they didn't surface in this specific session.
Step 6: Make the Updates
For each thing to capture, decide where it goes:
Agent instruction files
Add concise entries to the appropriate file(s). Match the existing style and tone — if the file uses bullet points, use bullet points; if it uses headers, use headers. Don't rewrite sections that don't need changing. Prefer adding to existing relevant sections over creating new ones.
Write for a future agent instance that has no memory of this session. Make entries actionable:
- Good: "Run
npm run lintbefore every commit — the CI gate will fail otherwise." - Bad: "We figured out that linting matters."
Project documentation
Update READMEs or other docs only if something genuinely changed that users/developers need to know. Don't add documentation for things that were already documented correctly.
Personal / cross-session lessons
If a lesson is specific to this project but not a fit for the agent instruction files (e.g., a nuance about how the team works, a personal workflow note), save it to:
docs/agent/memories/lessons-learned.md
Create the docs/agent/memories/ directory and the file if they don't exist yet. Use a simple
dated log format:
## YYYY-MM-DD
- [Lesson 1]
- [Lesson 2]
Append to the file; don't overwrite previous entries.
Step 7: Report What You Did
Give the user a short summary of what was updated:
- Which files were modified and what was added
- Anything you decided to skip and why
Keep it brief — one or two sentences per file is enough.
Principles
Be selective. A bloated AGENTS.md or CLAUDE.md that documents everything is worse than a focused one that documents the things that actually prevent mistakes. Ask yourself: "Would a capable developer miss this without being told?" If not, skip it.
Match the project's voice. If the existing instructions are terse and technical, be terse and technical. If they're friendly and explanatory, match that.
Don't pad. If there's nothing meaningful to capture from the session, say so. "Nothing significant to update — the session didn't surface new patterns or gotchas." is a perfectly valid outcome.