create-note

What this skill does

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:

   ```markdown
   **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
```markdown
# YYYY-MM-DD: Title

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

### Decision Template Structure
```markdown
# Decision: Title

Date: YYYY-MM-DD

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

### Troubleshooting Template Structure
```markdown
# Troubleshooting: Error Name

Last updated: YYYY-MM-DD

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

### Meeting Template Structure
```markdown
# 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:
```markdown
![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