capture-session

name: capture-session description: Extract decisions, action items, new context, and insights from the current session into LEARNINGS.md and auto-memory. Run before ending any substantive conversation. argument-hint: "[--dry-run]" allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion

Capture Session

Extract everything worth persisting from the current conversation and write it to the project's LEARNINGS.md file and auto-memory. This is the session-end counterpart to /capture-learning (which captures a single item). /capture-session sweeps the entire conversation.

When to Use

• Before ending any conversation where decisions were made, context was discovered, or work was done
• When the user says "wrap up", "that's it for now", "save this", or similar
• Proactively suggest this when the session has been substantive (30+ minutes, multiple tool calls, stakeholder context discussed)

Arguments

• --dry-run — Show what would be captured without writing anything

What to Extract

Review the FULL conversation and extract items in these categories:

1. Decisions (with rationale)

Things that were decided and WHY. These prevent future sessions from re-litigating settled questions.

• Code architecture choices
• Classification rules, business logic
• What to include/exclude from scope
• Tool or approach selections

2. Action Items

Work that needs to happen but hasn't been done yet. Include owner if known.

• Bug fixes identified but not implemented
• Follow-ups with stakeholders
• Things to verify next month/sprint
• Changes to propagate to other scripts/files

3. New Context

Information discovered during the session that wasn't previously known to the project. This is the most commonly lost category.

• Stakeholder preferences, workflows, pain points
• External systems or processes mentioned
• Business rules clarified
• Constraints or requirements surfaced

4. Bugs & Issues

Problems discovered, whether fixed or not.

• What was broken and how it manifested
• Root cause (if identified)
• Fix applied (if any)
• Remaining risk or edge cases

5. Deferred Investigations

Ideas, hypotheses, or potential improvements that came up but weren't pursued. Worth revisiting later.

• Performance improvements
• Feature ideas
• Refactoring opportunities
• "What if we..." discussions

Process

Capture Session Progress:
- [ ] Step 1: Review conversation for extractable items
- [ ] Step 2: Draft extraction (present to user)
- [ ] Step 3: User confirms/edits
- [ ] Step 4: Write to LEARNINGS.md
- [ ] Step 5: Update auto-memory for cross-session items
- [ ] Step 6: Confirm

Step 1: Review Conversation

Scan the full conversation history. For each category above, identify concrete items. Be specific — include file names, line numbers, amounts, names, dates. Vague entries are useless.

Good: "Kay confirmed EXEMPT FOOD tax group should only apply to CF-produced items; 3rd party non-taxable food gets NONTAXABLE (2026-04-02 call)"

Bad: "Tax group codes need to be reviewed"

Step 2: Present Draft

Show the user what you plan to capture, organized by category:

SESSION CAPTURE — DRAFT
=======================
Session: {brief description of what was done}
Date: {today}

DECISIONS (N items)
1. {decision} — Rationale: {why}

ACTION ITEMS (N items)
1. {item} — Owner: {who} — Due: {when, if known}

NEW CONTEXT (N items)
1. {context}

BUGS & ISSUES (N items)
1. {issue} — Status: {fixed/open/deferred}

DEFERRED INVESTIGATIONS (N items)
1. {idea}

Write to LEARNINGS.md? [Y/n]

Use AskUserQuestion to confirm. If --dry-run, stop here.

Step 3: User Confirms

If user says yes (or modifies), proceed. If user removes items, respect that. If user adds items, include them.

Step 4: Write to LEARNINGS.md

File location: LEARNINGS.md is always created/updated at PROJECT_ROOT (not feature directories), since learnings apply project-wide. To determine PROJECT_ROOT: if current directory matches */features/*, go up two levels; otherwise use current directory.

If LEARNINGS.md doesn't exist, create it:

# Session Learnings

> Persistent knowledge extracted from AI coding sessions.
> Captures decisions, context, action items, and insights that should survive between sessions.
> Add entries with `/capture-session` (full sweep) or `/capture-learning` (single item).

## Decisions

## Action Items

## Context

## Bugs & Issues

## Deferred Investigations

Append entries under the appropriate section. Each entry format:

- **[YYYY-MM-DD]** {content} *(source: {conversation/stakeholder/code review/etc.})*

For action items, use checkbox format:

- [ ] **[YYYY-MM-DD]** {action item} — Owner: {who}

Step 5: Update Auto-Memory

For items that are broadly relevant across sessions (not just task-specific), also write to auto-memory:

• New Context about stakeholders, external systems, or business rules → type: project or type: user memory
• Decisions that affect how future sessions should behave → type: feedback memory
• Don't duplicate — check existing memory files first

Skip this step if the project doesn't use auto-memory (no .claude/projects/ memory directory).

Step 6: Confirm

SESSION CAPTURED
================
Written to LEARNINGS.md:
  - {N} decisions
  - {N} action items
  - {N} context items
  - {N} bugs/issues
  - {N} deferred investigations

{If auto-memory updated}
Auto-memory updated:
  - {list of memory files created/updated}
{/If}

This context will be available in future sessions.

Agent Instruction Integration

For captured learnings to reliably appear in future sessions, the project should load LEARNINGS.md from its agent instructions. In Claude Code, add this to CLAUDE.md if that file exists:

@LEARNINGS.md

For Codex and other agents, add a short instruction in AGENTS.md telling agents to read LEARNINGS.md during orientation.

This integration is optional for writing the file, but it is what makes the captured context durable across future sessions. If neither instruction file references LEARNINGS.md, suggest adding the relevant line or instruction.

Guidance for Extraction Quality

Include if:

• It would save a future session from re-discovering something (> 5 min saved)
• A stakeholder said it (their words carry weight)
• It contradicts a prior assumption
• It affects multiple files or future work
• Someone would ask "why did we do it this way?"

Exclude if:

• It's obvious from reading the code or git log
• It's a temporary debugging step that's already resolved
• It's general programming knowledge
• It's already captured in CLAUDE.md, PROJECT_STATUS.md, or existing memory

Convert relative dates: "next month" → "May 2026", "Thursday" → "2026-04-03"

Error Handling