
claude-lab-notebook
Progressive disclosure note-taking system for research and experiments
- version
- 2.4.0
Install
/plugin install claude-lab-notebook@claude-lab-notebookRun it inside Claude Code after adding the marketplace with /plugin marketplace add mrariden/claude-lab-notebook.
Contents
Discovered from sourceSkills 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:
.claude/templates/{type}-template.md(user custom - checked first)$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
-
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
-
Ensure templates directory exists
mkdir -p .claude/templates -
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?"
- Look for
-
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
standupordaily:- Yesterday's Progress
- Today's Plan
- Blockers
- Note: Each standup is a snapshot in time - don't edit previous standups
For
retrospectiveorretro:- What Went Well
- What Could Be Improved
- Action Items
- Note: Each retrospective is a snapshot in time - don't edit previous retros
For
bug-reportorbug:- Summary
- Steps to Reproduce
- Expected Behavior
- Actual Behavior
- Environment
- Screenshots/Logs
For
feature-specorspec:- Overview
- Requirements
- User Stories
- Technical Approach
- Open Questions
- Success Criteria
For
interview:- Candidate
- Position
- Questions Asked
- Responses/Notes
- Assessment
- Recommendation
For
revieworcode-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
-
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/)
- Date-based:
-
Create the template
Build template with:
- Title format:
# {Type}: {Title}or# YYYY-MM-DD: {Title} - Date field if applicable
- Each section as
## Section Namewith placeholder content - CRITICAL: Always include
## Referencessection 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 - Title format:
-
Create the notes directory
mkdir -p notes/{type}s -
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) --> -
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-notesfirst 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.
-
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"
-
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
- Read from
-
Built-in templates:
/setup-notescopies 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
-
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
-
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
-
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-notesto 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
- Use Read tool to load
-
Create the note
- Use
create_fileto write the note - Place in correct directory
- Use proper filename format
- Use
-
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.
-
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.
-
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:

ā Incorrect - Just a text link:
[Figure description](figures/filename.png)
Guidelines:
- Use  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**

- 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.mdwith 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.mdnotes/experiments/notes/decisions/notes/troubleshooting/notes/research/
Step 3: Analyze Each Note
For each existing note file:
-
Read the content to understand what it contains
-
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
- Time-stamped experiments/attempts ā
-
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)
- Check git history:
-
Propose new filename:
YYYY-MM-DD-descriptive-name.md -
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:
-
Create archive directory for originals:
mkdir -p notes/archive/pre-migration -
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
-
Extract key findings from each file for INDEX.md
-
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
-
Create/update quick-reference.md with current working state if found
-
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:
- List all new files created
- Show updated INDEX.md
- Confirm all original files are archived
- 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.mdfrom 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
-
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
- If argument provided (e.g.,
-
Load the flavor file
- Read
flavors/{flavor}.mdto get:- Directory structure
- Protocol examples
- INDEX.md section templates
- If flavor file not found, warn and use
mlas default
- Read
-
Check current directory
- Verify we're in a project root (look for .git or ask user)
-
Create directory structure
- Create
.claude/rulesdirectory - Create
.claude/templatesdirectory - Create
configsdirectory - 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}
- Create
-
Copy built-in templates to .claude/templates/
Copy these template files from the plugin's
create-note/skill directory to.claude/templates/:experiment-template.mddecision-template.mdtroubleshooting-template.mdmeeting-template.md
How to find the plugin templates:
- The templates are co-located with the
/create-noteskill - 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
-
Save flavor choice
- Write the selected flavor name to
.claude/notebook-flavor.txt - This allows other skills to know which flavor is in use
- Write the selected flavor name to
-
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)
-
Create notes/INDEX.md
- Use the INDEX.md template below
- Include section headers from flavor's INDEX.md examples
-
Create notes/quick-reference.md
- Use the quick-reference.md template below
-
Create notes/README.md
- Quick guide to the system
- How to use the directories
-
Optional: Add to .gitignore
- Ask user if they want notes/local/ in .gitignore for personal notes
-
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
- INDEX.md is your map - Always read it first
- Failed attempts are valuable - Document them thoroughly
- Be specific - Include exact values and error messages
- Ask before loading - Don't waste context on irrelevant files
- Use line ranges -
view file.md 10 50for specific sections - Date everything - Chronology matters for understanding evolution
- Copy-pasteable configs - Not vague advice
- Link related notes - Build a knowledge graph using clickable links:
[Display](path.md) - Update quick-reference - Keep current best practices fresh
- All file references must be clickable - Use
[Text](path.md)format, never plain text paths - 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 experimentdecision- Add a recent decisiontroubleshooting- Add a troubleshooting guideconsolidate- Review recent notes and extract patternscleanup- Remove old entries, fix broken links
Steps
-
Read current INDEX.md
- Check what's already documented
- Note the last update date
-
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
-
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
-
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"
-
For troubleshooting:
- Add to "Known Issues" if ongoing problem
- Add to "All Troubleshooting Guides" list
- Include symptom + clickable link:
[Error title](troubleshooting/filename.md)
-
For consolidation:
- Scan experiments/ for recent notes
- Extract common patterns
- Group related findings
- Update "What Works" summary section
- Update "Known Issues" summary section
-
Update timestamp
- Change "Last updated:" to today's date
-
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":
-
Scan directories
ls -lt notes/experiments/*.md | head -10 ls -lt notes/decisions/*.md ls -lt notes/troubleshooting/*.md -
Read recent files
- Last 7 days of experiments
- Any new decisions
- New troubleshooting guides
-
Extract patterns
- What worked across multiple experiments?
- What failed multiple times?
- Are there contradictions to resolve?
-
Propose updates Show user proposed additions with clickable links: "I found these patterns from your recent work:
ā What Works:
- Learning rate 0.0003 consistently good (exp1, exp2, exp3)
- 4-layer architecture optimal for this task (architecture comparison)
ā Known Issues:
- Batch size >64 causes OOM on RTX 3090 (troubleshooting guide)
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":
- Remove entries older than 30 days from "Recent Activity"
- Check for dead links (files that don't exist)
- Alphabetize sections if requested
- Consolidate duplicate entries
- 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