notes

Notes

Two modes. Pick based on intent:

========================================

Notes mode — save, read, or organize persistent notes

Maintain persistent notes across Claude sessions.

Notes Directory

Global notes: ~/.claude/notes/

Structure:

~/.claude/notes/
├── projects/           # Per-project learnings
│   ├── narrative.md
│   ├── dbt.md
│   └── foxxed.md
├── patterns/           # Reusable patterns discovered
│   ├── snowflake.md
│   ├── streamlit.md
│   └── python.md
└── decisions/          # Key decisions and rationale
    └── YYYY-MM-DD-topic.md

Instructions

When asked to take notes or after completing significant work:

1. Identify the category:

   • Project-specific learning → ~/.claude/notes/projects/{project}.md
   • General pattern/technique → ~/.claude/notes/patterns/{topic}.md
   • Important decision → ~/.claude/notes/decisions/{date}-{topic}.md

2. Append to existing notes (don't overwrite):

   ## YYYY-MM-DD: Topic
   
   ### Context
   What was the task/problem?
   
   ### Solution
   What worked?
   
   ### Lessons
   - Key takeaway 1
   - Key takeaway 2
   

3. Reference notes when starting related work:

   • Check ~/.claude/notes/projects/{project}.md before working on a project
   • Review patterns that might apply

Commands

Save a note: Read the current content with the Read tool, then use the Edit tool to append:

## 2024-01-15: Topic here

Content here...

Read project notes: Use the Read tool on ~/.claude/notes/projects/narrative.md

List all notes: Use the Glob tool with pattern **/*.md in ~/.claude/notes/

Auto-Note Prompt

After completing a PR or significant task, Claude should ask:

"Should I add notes about this work to ~/.claude/notes/projects/{project}.md?"

========================================

Lessons mode — capture a lesson after a correction (or review past lessons)

Self-improvement loop for Claude - capture and review lessons from corrections.

Lessons Location

Global lessons: ~/.claude/notes/lessons/ Project lessons: .claude/lessons.md (in project root)

After ANY Correction

When the user corrects you, IMMEDIATELY:

1. Acknowledge the correction
2. Extract the pattern - What general rule would prevent this?
3. Write the lesson — use the Read tool to get current content, then the Edit tool to append:

Global lesson → append to ~/.claude/notes/lessons/global.md:

## YYYY-MM-DD: [Category] Brief Title

**Mistake:** What I did wrong
**Correction:** What I should have done
**Rule:** General rule to prevent this

Project-specific lesson → append to .claude/lessons.md:

## YYYY-MM-DD: Brief Title

**Mistake:** ...
**Rule:** ...

Reviewing Lessons (On Demand)

When the user asks to review lessons, or when starting a session where past mistakes are relevant:

• Read ~/.claude/notes/lessons/global.md
• Read .claude/lessons.md (skip if it doesn't exist)

Lesson Categories

• [Code Style] - Formatting, naming, conventions
• [Architecture] - Design decisions, patterns
• [Testing] - Test coverage, verification
• [Git] - Commit messages, PR workflow
• [Communication] - How to explain, ask questions
• [Tool Use] - Bash, SQL, specific tools

Self-Improvement Prompt

After being corrected, say:

"Let me add this to my lessons so I don't make this mistake again."

Then update the lessons file.

========================================

Migration

Consolidated from legacy skills. Pick the mode/lens based on intent.