Learn

Review conversation to identify learnings that should persist. Propose targeted updates for user approval.

Memory Targets

When to Create vs Update

Create new file when:

• Skill: Multi-step workflow emerged or domain expertise shared
• Rule: Guidance is file-pattern specific
• Agent: Specialized assistant persona needed
• Doc: Architecture/design decisions to preserve

Update existing when learning fits naturally into existing content.

Before creating docs: Check existing docs for correct placement. Consolidate rather than duplicate.

Workflow

CRITICAL: Never apply changes without explicit user approval.

1. Scan for Learnings

Look for:

• Explicit corrections ("no, do X instead")
• Guidance ("always X", "never Y", "prefer A over B")
• Preferences revealed through repeated feedback
• Workflows developed or refined
• Domain knowledge shared

If no learnings are found, inform the user and stop. Do not invent learnings.

2. Categorize

For each learning:

• Scope: Global (all projects) vs Project-specific
• Type: Preference, convention, knowledge, or process
• Confidence: Explicit (high), inferred (medium), pattern (low - verify)

For low-confidence (pattern-based) learnings, present them as questions rather than proposals: "I noticed you tend to X — would you like me to save this as a preference?"

When scope is ambiguous (global vs project), default to project-level and note the ambiguity in the proposal. Let the user decide to promote to global.

3. Determine Best Location

IMPORTANT: Actively search for the best placement. Don't default to CLAUDE.md.

Search Strategy

1. Search existing files for related content:

   • Grep for keywords from the learning
   • Check skills, rules, docs for thematic matches
   • Look at file structure and organization

2. Evaluate fit for each potential location:

   • Does the learning extend existing content naturally?
   • Would adding it here make the file too broad?
   • Is this the canonical place someone would look?

3. Consider creating new locations when:

   • Learning doesn't fit existing files well
   • Existing file would become unfocused
   • Topic deserves its own space
   • Multiple related learnings form a coherent theme

Location Decision Tree

Is this file-pattern specific? (e.g., "for .clj files...")
  → Yes → rules/*.md (create if no matching rule exists)

Is this a multi-step workflow or domain expertise?
  → Yes → skills/*/SKILL.md (create new skill if none fits)

Is this about a specialized assistant persona?
  → Yes → agents/*.md (create new agent)

Is this architectural/design knowledge?
  → Yes → docs/**/*.md (find or create appropriate doc)

Does this extend an existing skill's domain?
  → Yes → That skill's SKILL.md or references/

Is this a general preference/convention?
  → Yes → CLAUDE.md (project or global based on scope)

When to Suggest New Locations

Suggest creating a new skill when:

• A coherent workflow with 3+ steps emerged
• Domain-specific knowledge that doesn't fit elsewhere
• Could benefit other projects (global) or will be reused (project)

Suggest creating a new documentation file/category when:

• Architectural decisions need permanent record
• Complex topic needs structured explanation
• Related decisions are scattered and should consolidate

Suggest creating a new rule when:

• Guidance applies to specific file patterns
• Different file types need different treatment

Suggest creating a new agent when:

• Specialized expertise benefits from persona
• Multi-turn interaction pattern with specific knowledge

For frontmatter options when creating new skills or agents, read references/frontmatter-guide.md.

4. Consider Reorganization

Adding a learning may reveal opportunities to improve existing structure:

Consolidate when:

• Related content is scattered across multiple files
• Multiple small rules/skills could merge into one coherent resource
• Duplicate or overlapping guidance exists

Refactor when:

• Existing file has grown unfocused (split it)
• Learning reveals a better organizational structure
• Content belongs in a different location than where it currently lives

Reorganize when:

• New learning creates a theme that ties existing content together
• Skill references/ could absorb content from CLAUDE.md
• Project docs could absorb content from skills or rules

When proposing reorganization:

• Explain the current state and why it's suboptimal
• Show the proposed new structure
• List all files that would be affected
• Get explicit approval before making changes

5. Propose Updates

## Proposed: [Title]
**Source**: [Quote from conversation]
**Target**: [File path]
**Change**: Create | Add | Modify | Remove
**Location Rationale**: [Why this is the best location - what was considered]
**Duplication check**: [Confirmed no overlap with: list of checked locations]
**Content**:
[Proposed content - clear, concise, actionable]

If suggesting a new file, explain:

• Why existing files don't fit
• What this new location would contain
• How it relates to other memory targets

6. Get Approval

Use AskUserQuestion. Options: Accept, Modify, Skip, Change location.

If user wants a different location, update the proposal accordingly.

7. Apply

Only after approval: Read file, apply change, confirm.

Writing Guidelines

Write memory content that is:

• Specific: "Use bb test" not "use the test runner"
• Actionable: "Run tests before committing" not "testing is important"
• Concise: No filler, no redundancy
• Imperative: "Run X" not "You should run X"
• Non-duplicative: Don't restate what source code, directory structure, or other docs already provide

Source of Truth Checks

Before proposing documentation, verify:

• Does this information already exist in a reference file, skill, or source code?
• Could a reader discover this with ls, grep, or by reading the referenced file?
• If updating a skill, does another skill already own this knowledge?
• Would removing this text lose any information that isn't available elsewhere?

For detailed examples of proposals for different learning types (simple preferences, new rules, new skills, consolidation), read references/examples.md.