setup-notes

What this skill does

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:

```markdown
# 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:**
```markdown
- 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-directio