mrariden avatar

claude-lab-notebook

Progressive disclosure note-taking system for research and experiments

version
2.4.0

Install

/plugin install claude-lab-notebook@claude-lab-notebook

Run it inside Claude Code after adding the marketplace with /plugin marketplace add mrariden/claude-lab-notebook.

Contents

Discovered from source

Skills 5

You are helping the user create a new custom note type for their project.

Task

Guide the user through creating a new note type template that can be used with /create-note.

How Custom Templates Work

Custom templates are stored in .claude/templates/ in the user's project. When /create-note runs, it looks for templates in this order:

  1. .claude/templates/{type}-template.md (user custom - checked first)
  2. $SKILL_DIR/{type}-template.md (built-in - fallback)

By creating a template in .claude/templates/, users can:

  • Create entirely new note types
  • Override built-in templates with custom versions

Arguments

If the user provided a type name (e.g., /create-note-type standup), use that name directly.

Steps

  1. Get type name

    • If provided as argument: Use it directly
    • Otherwise ask: "What would you like to call this note type?"
    • Examples: standup, retrospective, bug-report, feature-spec, interview

    Naming rules:

    • Lowercase only
    • Use hyphens for multi-word names (e.g., bug-report)
    • No spaces or special characters
    • Keep it short and descriptive
  2. Ensure templates directory exists

    mkdir -p .claude/templates
    
  3. Check for existing template

    • Look for .claude/templates/{type}-template.md
    • If exists, ask: "A template for '{type}' already exists. Do you want to overwrite it?"
  4. Gather template sections

    Ask: "What sections should this note type have? I'll suggest some based on common patterns."

    Suggest sections based on type name:

    For standup or daily:

    • Yesterday's Progress
    • Today's Plan
    • Blockers
    • Note: Each standup is a snapshot in time - don't edit previous standups

    For retrospective or retro:

    • What Went Well
    • What Could Be Improved
    • Action Items
    • Note: Each retrospective is a snapshot in time - don't edit previous retros

    For bug-report or bug:

    • Summary
    • Steps to Reproduce
    • Expected Behavior
    • Actual Behavior
    • Environment
    • Screenshots/Logs

    For feature-spec or spec:

    • Overview
    • Requirements
    • User Stories
    • Technical Approach
    • Open Questions
    • Success Criteria

    For interview:

    • Candidate
    • Position
    • Questions Asked
    • Responses/Notes
    • Assessment
    • Recommendation

    For review or code-review:

    • PR/Code Reference
    • Summary of Changes
    • Feedback
    • Questions
    • Decision

    For other types:

    • Ask user to list their desired sections
    • Suggest common sections: Summary, Details, Action Items, References
  5. Determine filename pattern

    Ask: "How should files of this type be named?"

    Suggest based on type:

    • Date-based: YYYY-MM-DD-{description}.md (for recurring notes like standups)
    • Topic-based: {topic}.md (for one-off reference notes)
    • Combined: YYYY-MM-DD-{topic}.md (for dated topical notes)

    Also ask: "What directory should these notes go in?"

    • Suggest: notes/{type}s/ (e.g., notes/standups/, notes/bug-reports/)
  6. Create the template

    Build template with:

    • Title format: # {Type}: {Title} or # YYYY-MM-DD: {Title}
    • Date field if applicable
    • Each section as ## Section Name with placeholder content
    • CRITICAL: Always include ## References section at the end with clickable link examples
    • Use [Display text](relative/path.md) format for all file/note references

    Write to: .claude/templates/{type}-template.md

  7. Create the notes directory

    mkdir -p notes/{type}s
    
  8. Update INDEX.md (optional)

    Ask: "Should I add a section for '{type}' notes to INDEX.md?"

    If yes, add:

    ## All {Type}s
    <!-- Example:
    **YYYY-MM-DD: Title**
    - Tags: tag1, tag2
    - Finding: One-line summary
    - File: [{type}s/filename.md]({type}s/filename.md)
    -->
    
  9. Confirm completion

Template Format

Use this structure for the generated template with clickable links in References:

# {Type}: Descriptive Title

Date: YYYY-MM-DD

## Section 1
Placeholder text explaining what goes here

## Section 2
Placeholder text explaining what goes here

## Section 3
Placeholder text explaining what goes here

## References
- Related notes: [Note title](relative/path/to/note.md)
- Related experiments: [Experiment title](../experiments/YYYY-MM-DD-file.md)
- Related decisions: [Decision title](../decisions/topic.md)
- Code/config files: [File description](../../path/to/file.py)
- External links: [Link text](URL)

Example Templates

Standup Template

# YYYY-MM-DD: Daily Standup

## Yesterday
- What I completed

## Today
- What I plan to work on

## Blockers
- Any impediments (or "None")

## Notes
- Additional context

## References
- Related experiments: [Experiment title](../experiments/YYYY-MM-DD-file.md)
- Related tasks: [Task description](../path/to/file.md)

Bug Report Template

# Bug: Descriptive Title

Reported: YYYY-MM-DD
Status: Open | In Progress | Resolved

## Summary
Brief description of the bug

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS:
- Browser/Runtime:
- Version:

## Screenshots/Logs

[Paste screenshots or error logs]


## Investigation Notes
- Findings during debugging

## Solution
How it was fixed (fill in when resolved)

## References
- Related issues: [Issue title](other-bug.md)
- Related code: [File description](../../src/file.py)
- Related troubleshooting: [Troubleshooting title](../../troubleshooting/error.md)
- External links: [Link text](URL)

After Creation

Tell the user:

"āœ… Created new note type: {type}

šŸ“„ Template: .claude/templates/{type}-template.md šŸ“ Directory: notes/{type}s/ šŸ“‹ INDEX.md: {Updated | Not updated}

šŸš€ To use it:

/create-note {type}

Or when prompted for note type, enter: {type}

šŸ’” To customize further: Edit .claude/templates/{type}-template.md directly.

This template will be used automatically whenever you create a '{type}' note!"

Error Handling

  • If .claude/templates/ doesn't exist: Create it
  • If template already exists: Ask before overwriting
  • If INDEX.md doesn't exist: Skip INDEX update, warn user
  • If notes/ doesn't exist: Run /setup-notes first or create minimal structure

You are helping the user create a properly formatted note.

Template Resolution

All templates are stored in .claude/templates/ in the user's project.

  1. Determine template name:

    • User says "experiment" or type == 'experiment' → look for "experiment-template.md"
    • User says "decision" or type == 'decision' → look for "decision-template.md"
    • User says "custom-type" → look for "custom-type-template.md"
  2. Load template:

    • Read from .claude/templates/{type}-template.md
    • If not found, show error: "Template '{type}-template.md' not found in .claude/templates/"
    • List available templates by reading all files matching .claude/templates/*-template.md
  3. Built-in templates:

    • /setup-notes copies built-in templates to .claude/templates/ during initialization
    • Users can customize these templates directly
    • Users can create new templates with /create-note-type

Task

Guide the user through creating a note using the appropriate template.

Arguments

If the user provided a type argument (e.g., /create-note experiment), use that type directly instead of asking.

Valid types: experiment, decision, troubleshooting, meeting, research, or any custom template name.

Steps

  1. Determine note type

    • If type was provided as argument: Use it directly
    • Otherwise ask: "What type of note would you like to create?"
    • experiment: For documenting what you tried
    • decision: For recording why you made a choice
    • troubleshooting: For capturing how you fixed an error
    • meeting: For recording meeting notes and action items
    • research: For external references
  2. Get note details

    For experiment:

    • Ask for brief description
    • Suggest filename: notes/experiments/YYYY-MM-DD-{description}.md

    For decision:

    • Ask for topic name
    • Suggest filename: notes/decisions/YYYY-MM-{topic}.md

    For troubleshooting:

    • Ask for error/issue name
    • Suggest filename: notes/troubleshooting/{issue}-errors.md

    For meeting:

    • Ask for meeting topic/name
    • Suggest filename: notes/meetings/YYYY-MM-DD-{topic}.md
    • IMPORTANT: Meeting notes are snapshots in time - each meeting gets its own note
    • Do not edit previous meeting notes unless absolutely necessary
    • Link to previous meetings in the References section

    For research:

    • Ask for topic
    • Suggest filename: notes/research/{topic}.md
  3. Load appropriate template

    Read the template:

    • Use Read tool to load .claude/templates/{type}-template.md
    • If file doesn't exist, list available templates with Glob: .claude/templates/*-template.md
    • Show error: "Template not found. Run /setup-notes to initialize templates or /create-note-type {type} to create a custom template."

    Pre-fill template:

    • Fill in today's date automatically (YYYY-MM-DD format)
    • Pre-fill what you can from conversation context
    • Keep placeholder text for sections you don't have info for
  4. Create the note

    • Use create_file to write the note
    • Place in correct directory
    • Use proper filename format
  5. Gather INDEX metadata

    Every note MUST be added to INDEX.md. Ask the user:

    a. "What tags describe this? (comma-separated, e.g., 'optimizer, adamw, training')" b. "One-line key finding or summary?"

    These make the INDEX searchable without opening individual notes.

  6. Update INDEX.md (always)

    Add entry to the appropriate section with this format:

    **YYYY-MM-DD: [Note Title]**
    - Tags: tag1, tag2, tag3
    - Finding: One-line summary of key insight
    - File: [relative/path/to/note.md](relative/path/to/note.md)
    

    Section mapping:

    • experiment → "## All Experiments"
    • decision → "## All Decisions"
    • troubleshooting → "## All Troubleshooting Guides"
    • meeting → "## All Meetings"
    • research → "## All Research"

    Also add to "## Recent Activity" with today's date and title.

  7. Optionally update quick-reference.md

    Ask: "Did this change current best practices? Should I update quick-reference.md?"

    If yes:

    • Add to "What Works" if successful approach
    • Add to "Don't Do These" if failed approach
    • Update "Last Updated" section

Template References

Experiment Template Structure

# YYYY-MM-DD: Title

## Goal
## What I Tried
## Key Findings
## Failed Approaches (table)
## Configuration Used
## Next Steps
## References

Decision Template Structure

# Decision: Title

Date: YYYY-MM-DD

## Context
## Options Considered
## Decision
## Rationale
## Trade-offs
## When to Revisit
## References

Troubleshooting Template Structure

# Troubleshooting: Error Name

Last updated: YYYY-MM-DD

## Symptom
## Cause
## Solution
## Prevention
## Related Issues
## Example Occurrences

Meeting Template Structure

# Meeting: Title

Date: YYYY-MM-DD
Attendees: [Names]

## Agenda
## Discussion
## Decisions Made (table)
## Action Items
## Key Takeaways
## Follow-up
## References

Smart Pre-filling

Based on the conversation history:

  • Extract what the user was trying to do (→ Goal)
  • Extract what they tried (→ What I Tried)
  • Extract any errors mentioned (→ Failed Approaches)
  • Extract successful config (→ Configuration Used)
  • Note any related past experiments
  • CRITICAL: When referencing related notes or files, always use clickable markdown links: [Display text](relative/path)
  • Search INDEX.md to find related notes and add them as clickable links in References section

Figure Embedding

IMPORTANT: When adding figures to notes, always use inline markdown image syntax to make them viewable:

āœ… Correct - Embeds image inline:

![Figure description](figures/filename.png)

āŒ Incorrect - Just a text link:
[Figure description](figures/filename.png)

Guidelines:
- Use ![alt text](path) syntax so images render directly in markdown viewers
- Alt text should briefly describe what the figure shows
- Relative paths from the note location (e.g., figures/ subdirectory)
- After the embedded image, add a bullet list with key observations from the figure

Example:
## Figures

**Performance Comparison**
![Chart showing performance metrics over time](figures/performance-comparison.png)
- Metrics improved after configuration change
- Need further investigation on edge cases

## References and Backlinks

**IMPORTANT**: All references to other notes, files, or documentation should be
clickable backlinks:

āœ… **Correct** - Clickable backlink:
```markdown
- Related experiment: [2026-01-22-linear-decoder.md](../experiments/2026-01-22-linear-decoder.md)

āŒ Incorrect - Plain text or code blocks:
- Related experiment: experiments/2026-01-22-linear-decoder.md
- Dataset implementation: `path/to/example/dataset.py`

Guidelines:
- Use [display text](relative/path) syntax for all file and note references
- Use relative paths from the current note location
- Link display text should be descriptive (filename or human-readable description)
- Code files, config files, notebooks, and other notes should all be backlinks
- This makes notes navigable and allows clicking through to related content

Example References Section:
## References
- Related experiment: [2026-01-15-initial-approach.md](../experiments/2026-01-15-initial-approach.md)
- Implementation: [data_processor.py](../../src/data_processor.py)
- Configuration: [config.yaml](../../config/config.yaml)
- Documentation: [API Design](../research/api-design.md)

## Filename Formatting

Always use:
- Lowercase
- Hyphens instead of spaces
- YYYY-MM-DD format for dates
- Brief but descriptive

Good: `2025-01-13-learning-rate-sweep.md`
Bad: `Learning Rate Sweep.md`

## After Creation

Confirm to user:

"āœ… Created {filename}

šŸ“ Note type: {type}
šŸ“ Location: notes/{subdirectory}/{filename}
šŸ·ļø Tags: {tags}
šŸ“‹ Finding: {one-line finding}

āœ… Added to INDEX.md under '{section}'

Next steps:
- [ ] Fill in remaining details in the note
- [ ] Add clickable links to related notes in References section
- [ ] Link back from related notes if needed (bi-directional linking)

šŸ’” This note is now searchable via INDEX.md. I'll reference it in future sessions when relevant.
šŸ’” Remember: All file and note references should be clickable markdown links."

## Error Handling

- If `.claude/templates/` directory doesn't exist: "Run `/setup-notes` first to initialize the system"
- If template file doesn't exist: "Template not found. Available templates: [list from .claude/templates/]. Use `/create-note-type {type}` to create a custom template."
- If note file already exists: Ask if they want to overwrite or create with different name
- If INDEX.md doesn't exist: Warn but create note anyway

Migrate Existing Notes

Help the user migrate their existing notes to the lab notebook structure.

Your Task

Guide the user through migrating their existing notes into the organized note-taking protocol.

Arguments

If the user provided a source path (e.g., /migrate-notes ./docs), use that path directly instead of asking.

Step 1: Discover Existing Notes

If a source path was provided as argument, use it. Otherwise, ask the user where their existing notes are located. Common locations:

  • ./notes/ or ./docs/
  • ./README.md with embedded notes
  • Scattered markdown files in project root
  • A different notes directory

If they're unsure, search for markdown files:

find . -name "*.md" -type f | grep -v node_modules | grep -v .git

Step 2: Ensure Structure Exists

Check if the lab notebook structure exists. If not, suggest running /setup-notes first:

  • notes/INDEX.md
  • notes/experiments/
  • notes/decisions/
  • notes/troubleshooting/
  • notes/research/

Step 3: Analyze Each Note

For each existing note file:

  1. Read the content to understand what it contains

  2. Determine the type:

    • Time-stamped experiments/attempts → experiments/
    • Architectural/design choices → decisions/
    • Error solutions/fixes → troubleshooting/
    • External references/papers → research/
    • Meeting notes → meetings/
    • Current working state → quick-reference.md
    • Mixed content → Split into multiple files
  3. Extract or estimate a date:

    • Check git history: git log --follow --format="%ai" -- "filename" | tail -1
    • Use file modification time if no git history
    • Use today's date if truly unknown (note this in the file)
  4. Propose new filename: YYYY-MM-DD-descriptive-name.md

  5. Identify cross-references:

    • Note any references to other files or notes
    • CRITICAL: Convert all file references to clickable markdown links during migration
    • Use relative paths: [Display text](relative/path.md) format

Step 4: Present Migration Plan

Before making changes, show the user a migration plan:

## Migration Plan

| Original File | Type | New Location |
|--------------|------|--------------|
| old-notes.md | experiment | notes/experiments/2025-01-10-old-notes.md |
| config-ideas.md | decision | notes/decisions/2025-01-08-config-architecture.md |
| error-fixes.md | troubleshooting | notes/troubleshooting/common-errors.md |

### Actions:
1. Move X files to experiments/
2. Move Y files to decisions/
3. Move Z files to troubleshooting/
4. Split W mixed-content files
5. Update INDEX.md with findings
6. Archive originals to notes/archive/

Proceed with migration? (yes/no)

Step 5: Execute Migration

After user approval:

  1. Create archive directory for originals:

    mkdir -p notes/archive/pre-migration
    
  2. For each file:

    • Copy original to archive
    • Create new file in correct location with proper template structure
    • Preserve original content within the template
    • Add date header if missing
    • CRITICAL: Convert all file/note references to clickable markdown links [Display](path.md)
    • Add References section with clickable links to related notes
  3. Extract key findings from each file for INDEX.md

  4. Update INDEX.md with:

    • Summary of migrated experiments with clickable links
    • Key decisions documented with clickable links
    • Known issues/solutions with clickable links
    • Format: [Note title](relative/path.md) for all entries
  5. Create/update quick-reference.md with current working state if found

  6. Update cross-references:

    • After all files are migrated, review and add bi-directional links
    • If note A references note B, consider adding backlink from B to A
    • Ensure all paths are correct relative to the new locations

Step 6: Verify Migration

After migration:

  1. List all new files created
  2. Show updated INDEX.md
  3. Confirm all original files are archived
  4. Test that notes can be found by topic

Migration Templates

When restructuring content, use these formats and always include clickable links in References sections:

For experiments:

# YYYY-MM-DD: [Title from original]

## Goal
[Extract from original or ask user]

## What I Tried
[Extract from original]

## Key Findings
[Extract from original]

## Failed Approaches
| What I Tried | Why It Failed | Lesson Learned |
|--------------|---------------|----------------|
[Extract from original]

## Original Content
> [Preserve any content that doesn't fit above]

## References
- Related notes: [Note title](relative/path.md)
- Code files: [File description](../../path/to/file.py)
- External links: [Link text](URL)

For decisions:

# Decision: [Title]

Date: YYYY-MM-DD

## Context
[Extract from original]

## Options Considered
[Extract from original]

## Decision
[Extract from original]

## Rationale
[Extract from original]

## References
- Related experiments: [Experiment title](../experiments/YYYY-MM-DD-file.md)
- Related notes: [Note title](relative/path.md)
- External links: [Link text](URL)

For troubleshooting:

# Troubleshooting: [Error/Issue Name]

## Symptom
[Extract error messages from original]

## Cause
[Extract from original]

## Solution
[Extract steps from original]

## Prevention
[Extract or suggest based on content]

## Related Issues
- Similar problem: [Other error title](other-error.md)
- Root cause: [Decision title](../decisions/topic.md)

## References
- Related experiments: [Experiment title](../experiments/YYYY-MM-DD-file.md)

Important Notes

  • Always preserve original content - never delete without archiving
  • Ask before proceeding with each major step
  • If a note doesn't fit cleanly into one category, ask the user
  • Mixed-content files should be split into separate notes
  • CRITICAL: Update all internal links after moving files
  • CRITICAL: Convert all file/note references to clickable markdown links: [Display](path.md)
  • Add References sections to migrated notes with clickable links to related content
  • Use relative paths from the note location (e.g., ../experiments/file.md from decisions/)
  • For meeting notes: Keep each as a snapshot in time - don't edit old meetings

You are helping the user set up the note-taking protocol for their project.

Task

Create the complete directory structure and files for the progressive disclosure note-taking system, customized for the user's domain.

Flavors

Flavors customize the system for different domains. Available flavors:

  • ml (default): Machine learning experiments, hyperparameter tracking, research
  • software-engineering: Feature spikes, architecture decisions, API development
  • devops-sre: Incident response, runbooks, infrastructure decisions

Flavor files are located in flavors/ directory relative to this skill.

Steps

  1. Check for flavor argument

    • If argument provided (e.g., /setup-notes ml), use that flavor
    • If no argument, prompt user to select:
      Which flavor best matches your project?
      - ml (Machine Learning) - experiments, training runs, hyperparameters
      - software-engineering - spikes, architecture, API development
      - devops-sre - incidents, runbooks, infrastructure
      
  2. Load the flavor file

    • Read flavors/{flavor}.md to get:
      • Directory structure
      • Protocol examples
      • INDEX.md section templates
    • If flavor file not found, warn and use ml as default
  3. Check current directory

    • Verify we're in a project root (look for .git or ask user)
  4. Create directory structure

    • Create .claude/rules directory
    • Create .claude/templates directory
    • Create configs directory
    • Create notes/ with subdirectories from flavor's directory list
    • Example for ml: notes/{experiments,decisions,troubleshooting,research}
    • Example for software-engineering: notes/{spikes,decisions,troubleshooting,architecture,research}
  5. Copy built-in templates to .claude/templates/

    Copy these template files from the plugin's create-note/ skill directory to .claude/templates/:

    • experiment-template.md
    • decision-template.md
    • troubleshooting-template.md
    • meeting-template.md

    How to find the plugin templates:

    • The templates are co-located with the /create-note skill
    • Use Glob to find them: Search for **/skills/create-note/*-template.md
    • Read each template file from the plugin directory
    • Write it to .claude/templates/ with the same filename

    This makes templates:

    • Always available in a known location
    • Easy for users to customize
    • Portable with the project
  6. Save flavor choice

    • Write the selected flavor name to .claude/notebook-flavor.txt
    • This allows other skills to know which flavor is in use
  7. Create .claude/rules/note-taking-protocol.md

    • Use the protocol template below
    • Replace {{DIRECTORY_STRUCTURE}} with flavor's directory tree
    • Replace {{PROTOCOL_EXAMPLES}} with flavor's "When to Load Additional Files" examples
    • Replace {{SESSION_EXAMPLE}} with flavor's progressive disclosure session example
    • Replace {{PRIMARY_DIR}} with flavor's primary directory (experiments/spikes)
  8. Create notes/INDEX.md

    • Use the INDEX.md template below
    • Include section headers from flavor's INDEX.md examples
  9. Create notes/quick-reference.md

    • Use the quick-reference.md template below
  10. Create notes/README.md

    • Quick guide to the system
    • How to use the directories
  11. Optional: Add to .gitignore

    • Ask user if they want notes/local/ in .gitignore for personal notes
  12. Confirm completion

    • List all created files
    • Explain next steps
    • Remind them Claude will auto-read .claude/rules/ on next session

.claude/rules/note-taking-protocol.md Template

Use this template, replacing placeholders with flavor-specific content:

# Note-Taking Protocol

*This file is automatically loaded by Claude Code from .claude/rules/*

## Context Efficiency Protocol (CRITICAL)

**Progressive Disclosure System**: Never load all notes at once. Follow this strict hierarchy:

1. **ALWAYS start by reading** `notes/INDEX.md` (quick reference, ~200 lines max)
2. **Then read** `notes/quick-reference.md` (current working state)
3. **Ask before loading** any other files
4. **Use view tool with line ranges** when you only need specific sections
5. **Never load** entire `notes/` directory at once

## Directory Structure

~~~
project/
ā”œā”€ā”€ .claude/
│   ā”œā”€ā”€ templates/                    # Notes template dir
│   ā”œā”€ā”€ notebook-flavor.txt           # Selected flavor
│   └── rules/
│       └── note-taking-protocol.md   # This file (auto-loaded)
ā”œā”€ā”€ notes/
│   ā”œā”€ā”€ INDEX.md                       # Master index - READ FIRST
│   ā”œā”€ā”€ quick-reference.md             # Current working state
{{DIRECTORY_STRUCTURE}}
└── configs/                           # Working configurations
~~~

## Workflow for Every Session

### Session Start

1. **Read `notes/INDEX.md`** - This is mandatory, always do this first
2. **Read `notes/quick-reference.md`** - Get current state
3. **Ask user**: "What are you working on today?"
4. **Based on their answer**, suggest relevant notes to load
5. **Load only relevant files** using the `view` tool

### When to Load Additional Files

{{PROTOCOL_EXAMPLES}}

### What NOT to Do

āŒ Don't say: "Let me read all your notes"
āŒ Don't load multiple files without asking
āŒ Don't read entire files when you only need a section
āŒ Don't skip reading INDEX.md (it's always required)

āœ… Do say: "Based on INDEX.md, I found relevant info in X. Should I read it?"
āœ… Do use `view` tool with line ranges for large files
āœ… Do ask user to specify which time period matters
āœ… Do read INDEX.md and quick-reference.md at session start

### During Work

- Keep rough notes of what you're trying
- Document failures as they happen (these are valuable)
- Track configuration changes

### Session End

**Ask user which type of note to create:**

1. **Primary note** (most common)
   - Create in `notes/{{PRIMARY_DIR}}/YYYY-MM-DD-description.md`
   - Document: goal, what tried, what worked, what failed, next steps

2. **Decision note** (for architectural/design choices)
   - Create in `notes/decisions/YYYY-MM-topic.md`
   - Document: context, options considered, decision, rationale, trade-offs

3. **Troubleshooting note** (for error patterns)
   - Create in `notes/troubleshooting/topic-errors.md`
   - Document: symptom, cause, solution, prevention

**After creating note, ask:**
- "Should I update `notes/INDEX.md`?" (if significant finding)
- "Should I update `notes/quick-reference.md`?" (if current best practice changed)

## Progressive Disclosure in Practice

{{SESSION_EXAMPLE}}

## File Naming Conventions

- **Primary notes**: `YYYY-MM-DD-brief-description.md` (chronological)
- **Decisions**: `YYYY-MM-topic-name.md` (topical)
- **Troubleshooting**: `topic-name-errors.md` or `error-type.md` (topical)
- **Research**: `topic-name.md` or `paper-name.md` (topical)

Always use lowercase with hyphens, no spaces.

## Linking Conventions (CRITICAL)

**All file and note references must be clickable markdown links.**

āœ… **Correct:**
```markdown
- Related experiment: [Learning rate sweep](../experiments/2025-01-13-lr-sweep.md)
- Config file: [Training config](../../configs/config.yaml)
- Decision: [Architecture choice](../decisions/2025-01-architecture.md)

āŒ Incorrect:

- Related experiment: experiments/2025-01-13-lr-sweep.md
- Config file: configs/config.yaml
- Decision: See 2025-01-architecture.md

Format: [Display text](relative/path.md)

  • Display text should be descriptive (note title or file description)
  • Use relative paths from the current note location
  • In INDEX.md: All entries must link to their files
  • In note References sections: All related notes/files must be clickable
  • For meeting notes: Each meeting is a snapshot in time - don't edit old meetings, link to them instead

Benefits:

  • Click through to related content directly
  • Navigate knowledge graph easily
  • IDE integration for "go to definition"
  • Enables bi-directional linking

Critical Reminders

  1. INDEX.md is your map - Always read it first
  2. Failed attempts are valuable - Document them thoroughly
  3. Be specific - Include exact values and error messages
  4. Ask before loading - Don't waste context on irrelevant files
  5. Use line ranges - view file.md 10 50 for specific sections
  6. Date everything - Chronology matters for understanding evolution
  7. Copy-pasteable configs - Not vague advice
  8. Link related notes - Build a knowledge graph using clickable links: [Display](path.md)
  9. Update quick-reference - Keep current best practices fresh
  10. All file references must be clickable - Use [Text](path.md) format, never plain text paths
  11. Meeting notes are snapshots - Each meeting gets its own note, don't edit previous meetings

Remember: This system optimizes for findability over storage. Every note should answer: "How will future-me find this when I need it?"


## INDEX.md Template

```markdown
# Project Notes Index

Last updated: [TODAY'S DATE]

## Quick Links
- [Current Best Config](../configs/)
- [Quick Reference](quick-reference.md)

## What Works (Summary)
- Add successful approaches here as you discover them

## Known Issues
- Add problems here as you encounter them

## Recent Activity (Last 7 days)
- [TODAY]: Initialized note-taking system

{{INDEX_SECTIONS}}

quick-reference.md Template

# Quick Reference - Current Project State

Last updated: [TODAY'S DATE]

## What's Working Right Now
```yaml
# Add current working config

Don't Do These (Failed Approaches)

  • āŒ Add failures here

Current Best Practices

  • āœ“ Add successes here

Open Questions

  • Things to investigate

Last Updated

  • [TODAY]: Initialized system

## After Setup

Tell the user:

"Setup complete!

**Flavor:** {selected_flavor}

**Created:**
- `.claude/rules/note-taking-protocol.md` (auto-loaded protocol)
- `.claude/notebook-flavor.txt` (flavor configuration)
- `.claude/templates/` (note templates - customize as needed)
  - experiment-template.md
  - decision-template.md
  - troubleshooting-template.md
  - meeting-template.md
- `notes/INDEX.md` (your knowledge map)
- `notes/quick-reference.md` (current state)
- `notes/{directories from flavor}/` (organized by type)
- `configs/` (configuration file storage)

**Templates:**
Built-in templates copied to `.claude/templates/` and ready to use via `/create-note`:
- experiment (or spike for software-engineering flavor)
- decision
- troubleshooting
- meeting

**Next steps:**
1. Start your next Claude Code session
2. I'll automatically read `.claude/rules/` and follow the protocol
3. At the end of your session, I'll ask if you want to create a note

The system optimizes for findability - you'll never repeat the same mistake twice!"

## Error Handling

- If directories exist: Ask before overwriting
- If not in project root: Warn and ask for confirmation
- If flavor not found: Warn and fall back to `ml`

You are helping the user maintain their knowledge base index.

Task

Update notes/INDEX.md to reflect recent work and maintain organization.

Arguments

If the user provided an action argument (e.g., /update-index consolidate), perform that action directly.

Valid actions:

  • experiment - Add a recent experiment
  • decision - Add a recent decision
  • troubleshooting - Add a troubleshooting guide
  • consolidate - Review recent notes and extract patterns
  • cleanup - Remove old entries, fix broken links

Steps

  1. Read current INDEX.md

    • Check what's already documented
    • Note the last update date
  2. Ask what to add Options:

    • "I just finished an experiment" → Add to Recent Activity + All Experiments
    • "I made a decision" → Add to Decisions list
    • "I solved an error" → Add to Known Issues or Troubleshooting
    • "Review recent notes" → Scan notes/ directories and suggest updates
    • "Consolidate findings" → Review multiple experiments and extract patterns
  3. For new experiment:

    • Add one-line summary to "Recent Activity"
    • Add to "All Experiments" chronologically
    • If significant: Add to "What Works" or "Known Issues"
    • CRITICAL: Include clickable link to actual note file using [Note title](relative/path.md) syntax
  4. For new decision:

    • Add to "All Decisions" list
    • Add one-line summary with clickable link: [Decision title](decisions/filename.md)
    • If it affects current practice: Note in "What Works"
  5. For troubleshooting:

    • Add to "Known Issues" if ongoing problem
    • Add to "All Troubleshooting Guides" list
    • Include symptom + clickable link: [Error title](troubleshooting/filename.md)
  6. For consolidation:

    • Scan experiments/ for recent notes
    • Extract common patterns
    • Group related findings
    • Update "What Works" summary section
    • Update "Known Issues" summary section
  7. Update timestamp

    • Change "Last updated:" to today's date
  8. Show changes

    • Display the diff or summarize what was added
    • Ask for confirmation before saving

INDEX.md Structure

IMPORTANT: All file references in INDEX.md MUST be clickable markdown links using [Display text](relative/path.md) syntax.

# Project Notes Index

Last updated: YYYY-MM-DD

## Quick Links
- [Current Best Config](../configs/)
- [Quick Reference](quick-reference.md)

## What Works (Summary)
- **Topic**: One-line summary (see [Experiment title](experiments/YYYY-MM-DD-file.md))

## Known Issues
- **Issue**: One-line description (see [Troubleshooting title](troubleshooting/file.md))

## Recent Activity (Last 7 days)
- YYYY-MM-DD: [What happened](experiments/YYYY-MM-DD-file.md) - Brief summary

## All Experiments
- YYYY-MM-DD: [Experiment title](experiments/YYYY-MM-DD-file.md) - Brief result

## All Decisions
- [Decision title](decisions/file.md) - One-line summary

## All Troubleshooting Guides
- [Error Name](troubleshooting/file.md) - Symptom

## All Meetings
- [Meeting title](meetings/YYYY-MM-DD-topic.md) - Key takeaways

Smart Consolidation

When user asks to "consolidate" or "review":

  1. Scan directories

    ls -lt notes/experiments/*.md | head -10
    ls -lt notes/decisions/*.md
    ls -lt notes/troubleshooting/*.md
    
  2. Read recent files

    • Last 7 days of experiments
    • Any new decisions
    • New troubleshooting guides
  3. Extract patterns

    • What worked across multiple experiments?
    • What failed multiple times?
    • Are there contradictions to resolve?
  4. Propose updates Show user proposed additions with clickable links: "I found these patterns from your recent work:

    āœ… What Works:

    āŒ Known Issues:

    Should I add these to INDEX.md?"

One-Line Summary Guidelines

Good summaries are:

  • āœ… Specific: "LR=0.0003 optimal for 4-layer model"
  • āœ… Actionable: "Use batch_size ≤32 to avoid OOM"
  • āœ… Concise: One line with key metric or finding

Bad summaries:

  • āŒ Vague: "Tested learning rates"
  • āŒ Too long: Full paragraph
  • āŒ No context: "It worked"

Recent Activity Format

Keep last 7-14 days visible with clickable links:

## Recent Activity (Last 7 days)
- 2025-01-13: [Learning rate sweep](experiments/2025-01-13-lr-sweep.md) - 0.0003 optimal
- 2025-01-12: [Architecture comparison](experiments/2025-01-12-arch.md) - 4 layers best
- 2025-01-11: [Optimizer test](experiments/2025-01-11-optimizer.md) - AdamW > SGD

Format: YYYY-MM-DD: [Note title](relative/path.md) - Brief result

Auto-archive older entries to keep this section focused.

After Update

Tell user:

"āœ… Updated notes/INDEX.md

šŸ“ Changes:

  • Added to Recent Activity: {summary}
  • Updated {section}: {what changed}
  • Last updated: {today's date}

šŸ’” Your knowledge map is current. I'll reference these findings in future sessions."

Maintenance Mode

If user says "clean up INDEX" or "reorganize":

  1. Remove entries older than 30 days from "Recent Activity"
  2. Check for dead links (files that don't exist)
  3. Alphabetize sections if requested
  4. Consolidate duplicate entries
  5. Verify all links work

Error Handling

  • If INDEX.md doesn't exist: "Run /setup-notes first"
  • If can't parse structure: Offer to rebuild from scratch
  • If referenced files missing: Note broken links and ask to fix

Sponsors

Details

Marketplace
mrariden/claude-lab-notebook
Source
plugins/claude-lab-notebook
Author
Michael Rariden
Category
Productivity
Keywords
notes, research, experiments, knowledge-management, documentation