# Creating Research Notes

This skill documents how to create new research notes for the journal.

## Directory Structure

Each note lives in `blog/content/notes/{NNN}-{slug}/`:

```
blog/content/notes/
├── 001-picking-a-problem/
│   ├── meta.yaml         # Metadata, prompts, navigation
│   └── content.md        # Prose content
├── 002-building-the-scaffolding/
│   ├── meta.yaml
│   ├── content.md
│   └── files/            # Optional: expandable file contents
│       ├── vision.md
│       ├── architecture.md
│       └── roadmap.md
└── 003-research-planning/
    ├── meta.yaml
    └── content.md
```

## Step 1: Create the Directory

```bash
mkdir -p blog/content/notes/{NNN}-{slug}
```

Use zero-padded 3-digit ID (001, 002, 003...) and kebab-case slug.

## Step 2: Create meta.yaml

Required fields:

```yaml
id: "003"
slug: 003-research-planning
date: "2026-02-07"
title: Research Planning
preview: "Short description shown in note list (1-2 sentences)"

prompts:
  - id: unique-id
    label: Button label shown to user
    content: |
      The actual prompt content that gets copied.
      Can be multi-line.

  - id: another-prompt
    label: Another Prompt
    content: |
      Second prompt content here.

filesCreated: []  # Or list of files if any

navigation:
  prev:
    slug: 002-building-the-scaffolding
    id: "002"
    title: Understanding the Project
  next: null  # Or next note reference
```

### Optional: skillsUsed

When documenting Claude Code skills/commands used during research:

```yaml
skillsUsed:
  - name: do-parallel
    command: /do-parallel
    description: Execute tasks in parallel waves with optimal agent selection and review
    usage: |
      ---
      description: Execute tasks in parallel waves...
      argument-hint: <task list or "from todo">
      allowed-tools: Task, Read, Write, Edit, Glob, Grep, Bash, TodoWrite
      ---

      Execute these tasks in parallel waves with proper review: $ARGUMENTS

      ## Instructions
      [FULL command definition from ~/.claude/commands/{command}.md]
```

**IMPORTANT**: The `usage` field should contain the ACTUAL command file contents from `~/.claude/commands/`, not just example usage.

### Optional: filesCreated

When the note documents files that were created:

```yaml
filesCreated:
  - name: vision.md
    description: Core thesis, axioms, paradoxes, and narrative
  - name: architecture.md
    description: System layers, code sketches, data structures
```

These files should exist in `files/` subdirectory.

## Step 3: Create content.md

Write the prose content in Markdown:

```markdown
## The Method

Explain what you did and why.

## Section Two

More content here.

- Bullet points work
- As do **bold** and *italic*

### Subsection

Deeper explanation.

## What I Learned

Reflections on the process.

## Next Steps

What comes next in the research.
```

Supported Markdown features:
- Headings (h2, h3)
- Paragraphs
- Bullet lists (ul)
- Numbered lists (ol)
- Bold and italic text
- Inline code with backticks

## Step 4: Add Files (Optional)

If `filesCreated` references files, create them in `files/`:

```bash
mkdir -p blog/content/notes/{NNN}-{slug}/files
```

Each file should be the complete content that will be shown in an expandable section.

## Step 5: Update Previous Note Navigation

Edit the previous note's `meta.yaml` to add the `next` navigation:

```yaml
navigation:
  prev:
    slug: 001-picking-a-problem
    id: "001"
    title: Picking a Problem
  next:
    slug: 003-research-planning
    id: "003"
    title: Research Planning  # Add this
```

## Step 6: Verify

```bash
cd blog && npm run dev
```

Check:
- [ ] Note appears in list at `/maxwell`
- [ ] Note renders at `/maxwell/notes/{slug}`
- [ ] Prompts have working copy buttons
- [ ] Skills section shows with expandable usage (if skillsUsed)
- [ ] Files section shows with expandable content (if filesCreated)
- [ ] Prev/next navigation works
- [ ] Build succeeds: `npm run build`

## Schema Reference

### NoteMeta Interface

```typescript
interface NoteMeta {
  id: string;
  slug: string;
  date: string;
  title: string;
  preview: string;
  prompts: Prompt[];
  skillsUsed?: SkillUsed[];
  filesCreated: FileCreated[];
  navigation: {
    prev: NavLink | null;
    next: NavLink | null;
  };
}

interface Prompt {
  id: string;
  label: string;
  content: string;
}

interface SkillUsed {
  name: string;
  command: string;
  description: string;
  usage?: string;  // Full command definition
}

interface FileCreated {
  name: string;
  description: string;
}

interface NavLink {
  slug: string;
  id: string;
  title: string;
}
```

## Key Files

| File | Purpose |
|------|---------|
| `blog/src/lib/content.ts` | Content loaders |
| `blog/src/app/maxwell/notes/[slug]/page.tsx` | Dynamic route |
| `blog/src/components/notes/NoteHeader.tsx` | Note header |
| `blog/src/components/notes/PromptsSection.tsx` | Prompts with copy |
| `blog/src/components/notes/SkillsSection.tsx` | Skills/commands |
| `blog/src/components/notes/FilesSection.tsx` | Expandable files |
| `blog/src/components/notes/NoteFooter.tsx` | Navigation |