self-improving-session

Good session learning captures durable guidance, not conversational residue.

Extract reusable lessons from the current session and propose the smallest valid update to CLAUDE.md. The goal is not to remember everything. The goal is to preserve only rules that improve future sessions while keeping the rule set small.

This skill works standalone. It can learn from ordinary sessions or from sessions shaped by self-improving-prompt.

When paired together:

• self-improving-prompt shapes task framing and execution behavior
• self-improving-session reviews the resulting session and extracts durable workflow rules

This skill should learn from behavior patterns, corrections, and repeated outcomes, not from storing the refined prompt text itself.

Security and Runtime

• Instruction-only skill; no bundled scripts or external services required
• No credentials, API keys, or network access required for normal use
• Does not modify system configuration; may propose writing to CLAUDE.md files after user confirmation
• Optional session-end automation belongs in README only and is not required for core skill behavior

Quick Reference

Core Principle

Prefer under-learning to over-learning. A noisy CLAUDE.md harms future sessions more than a missed weak signal. The best outcome is often:

• no change, or
• one compact replacement that improves existing guidance without increasing rule count

Step 1: Scan the Session

Look for two categories:

A. Workflow preferences and corrections

• Explicit user corrections
• Repeated output-format preferences
• Collaboration-flow preferences
• Tool-usage preferences
• Repeated self-improving-prompt workflow choices

Only treat a signal as durable if it appears reusable across tasks.

B. Project rules and conventions

• Coding conventions
• Architecture decisions
• Tech-stack preferences
• Testing and deployment rules
• Team or repo-specific collaboration conventions

Step 2: Filter Noise

Skip:

• One-off debugging details
• Temporary workarounds
• Facts already derivable from code
• Rules already documented clearly elsewhere
• Full prompts produced by self-improving-prompt
• Generic praise such as "perfect" or "yes exactly" unless it clearly confirms a reusable workflow rule

Do not learn courtesy language as a durable preference. See references/rule-quality.md for what counts as a strong, reusable rule versus noise.

Step 3: Classify Scope

Choose the destination by scope:

• Cross-project workflow rules -> ~/.claude/CLAUDE.md
• Project-specific engineering conventions -> project CLAUDE.md
• Temporary lessons or one-off incident notes -> separate task notes, not CLAUDE.md

Do not mix personal workflow rules into a project convention section.

Step 4: Apply Confidence Rules

Use one consistent threshold:

• Explicit correction or explicit permanent instruction -> [stable]
• Same reusable preference observed 2 times across meaningfully different tasks -> [tentative]
• Same reusable preference observed 4 times across multiple task contexts -> [stable]

If the evidence is weaker than that, do not learn it.

Step 5: Merge Carefully

• Deduplicate rules with the same meaning
• Merge wording variants into one concise rule
• Do not let a new [tentative] overwrite an existing [stable]
• Only explicit correction can rewrite an existing [stable]
• Keep the total rule set compact
• Prefer compressing or replacing low-quality rules rather than appending near-duplicates
• Prefer replacing multiple weaker rules with one stronger rule when possible
• If existing rules already cover the behavior, propose no change

Rule Budget

To prevent CLAUDE.md bloat:

• Keep global workflow rules under about 20 bullets
• Keep project-specific convention rules under about 15 bullets unless the project genuinely requires more
• If a section grows too large, merge or compress instead of appending
• A single session should usually propose no more than 3 new rules unless the user explicitly asks for broader guidance cleanup
• If the target CLAUDE.md section is already over budget, compact first and do not append new rules unless the user explicitly approves
• Zero new rules is a normal and healthy outcome

Confidence Markers

• [tentative]: observed twice and likely reusable, but not well validated yet
• [stable]: explicitly stated or validated repeatedly
• [corrected: YYYY-MM-DD]: old rule superseded by explicit user correction

Example:

- Prefer concise final answers by default [stable]
- Show refined prompts only when refinement materially improves execution [stable]
- Write scope explicitly for risky code tasks [tentative]
- ~~Always use popup confirmation~~ -> Use compare-first only when refinement adds substantial value [corrected: 2026-04-14]

Event Consumption from self-improving-prompt

If self-improving-prompt emits abstract events, use them as weak evidence only.

Examples:

• choose_refined
• choose_original
• explicit_no_compare
• explicit_compare_first

Rules:

• A single event is not enough to create a durable rule unless paired with an explicit verbal instruction
• Repeated events may support a [tentative] or [stable] rule using the thresholds above
• The refined prompt may have shaped the session, but the refined prompt text itself should not be stored as a durable rule
• Never store the refined prompt text itself

Confirmation Before Writing

By default, show the user:

• new rules to add
• existing rules to update
• target file

Then wait for confirmation before writing.

Skip confirmation only when:

• the user explicitly says to update directly, or
• the skill is running automatically at session end with prior permission to write

If interactive confirmation is unavailable, fall back to plain-text confirmation.

Output Format

When writing rules:

• Use concise markdown bullets
• Separate Global Workflow Rules from Project Conventions
• Keep each rule broadly reusable
• Include a confidence marker at the end
• Prefer the smallest valid update: no change, replacement, merge, or at most a few additions

Before adding a rule, validate it against references/rule-quality.md.

Notes

• Do not store secrets, passwords, tokens, or sensitive personal data
• Do not store full prompt text
• Do not store temporary task state
• If there is nothing durable to learn, say so plainly

Optional session-end automation examples are documented in README.md. They are convenience setup, not a requirement of the skill itself.