Adding Notes

Adding Notes to Second Brain

Add content to the knowledge base with proper frontmatter, tags, summaries, and wiki-links.

Content Type Routing

Detect type from URL, then load the appropriate reference file.

YouTube Classification

YouTube URLs require sub-classification before processing:

1. Known podcast channel? → references/content-types/podcast.md
2. Known talk channel OR conference title? → references/content-types/talk.md
3. Tutorial signals? → references/content-types/youtube.md with isTechnical: true
4. Default → references/content-types/youtube.md

See references/content-types/youtube.md for full classification logic and channel lists.

Scripts Reference

Only use scripts that fetch external data or perform complex processing:

Do NOT use scripts for these trivial operations — do them inline:

• Slug generation: "My Title Here" → my-title-here (lowercase, spaces to hyphens)
• Author check: Use Glob tool with content/authors/*{lastname}*.md
• Frontmatter templates: Write YAML directly
• Tag lookup: Use Grep tool or rely on knowledge from prior notes

Workflow Phases

Phase 1: Type Detection → Route to content-type file
Phase 2: Parallel Metadata Collection → Per-type agents
Phase 3: Author Creation → See references/author-creation.md
Phase 4: Content Generation → Apply writing-style, generate body
Phase 4.5: Connection Discovery → Find genuine wiki-link candidates (if any exist)
Phase 5: Quality Validation → Parallel validators
Phase 6: Save Note → Write to content/{slug}.md with link density report
Phase 7: MOC Placement → Suggest placements + check MOC threshold
Phase 8: Quality Check → Run pnpm lint:fix && pnpm typecheck

Phase 1: Type Detection & Dispatch

1. Detect type from URL using the Content Type Routing table above (no script needed)
2. Load the content-type reference file for detailed handling
3. Detect isTechnical flag (see content-type file for criteria)

Phase 2: Metadata Collection

Spawn parallel agents as specified in the content-type file. Each file lists:

• Required scripts to run
• Agent configuration
• Special handling notes

If isTechnical: true: Also spawn code extraction agent (see references/code-extraction.md).

Phase 3: Author Creation

For external content types, authors are required. Check existence with Glob (no script needed):

Glob: content/authors/*{lastname}*.md

Handle by result:

For partial matches, use the AskUserQuestion tool:

question: "Is [Author Name] the same person as this existing author?"
header: "Author Match"
multiSelect: false
options:
  - label: "Yes, use existing"
    description: "Use the existing author profile"
  - label: "No, create new"
    description: "Create a new author profile"

Quick creation flow:

1. WebSearch: [Author Name] official site bio
2. Extract: bio, avatar, website, socials
3. Write author file directly (no script):

---
name: "Author Name"
slug: "author-name"
bio: "1-2 sentence description"
avatar: ""
website: ""
socials:
  twitter: ""
  github: ""
  linkedin: ""
  youtube: ""
---

4. Save to content/authors/{slug}.md (slug = lowercase name, spaces to hyphens)

Tip: Add aliases field to authors who go by multiple names (e.g., "DHH" → aliases: ["David Heinemeier Hansson"]).

Phase 4: Content Generation

1. Load writing-style skill (REQUIRED): Read .claude/skills/writing-style/SKILL.md
2. Load linking philosophy (REQUIRED): Read .claude/skills/adding-notes/references/linking-philosophy.md
3. If isTechnical: collect code snippets from Phase 2
4. Compile frontmatter using template from content-type file
5. Generate body with wiki-links (see Phase 4.5 for connection discovery)
6. Add diagrams if applicable (see references/diagrams-guide.md)

Tags: 3-5 relevant tags. Use tags you've seen in prior notes or Grep for similar content to find existing tags.

Summary: Frame as a core argument, not a description. What claim does this content make?

Phase 4.5: Connection Discovery

Before finalizing content, search for genuinely related notes. Only add connections that organically make sense.

1. Same author check (highest priority): If author exists, find their other works:

   Grep pattern: "authors:.*{author-slug}" glob: "content/*.md"
   

2. Tag-based discovery: For each tag, find notes with that tag:

   Grep pattern: "tags:.*{tag}" glob: "content/*.md" limit: 5
   

3. Evaluate candidates: For each potential connection, ask: "Would I naturally reference this when discussing the topic?" If the answer is no, don't force the link.

Connection quality over quantity:

• Add links only when the relationship is genuine and useful
• If no notes genuinely relate, save as an orphan—that's fine
• Forced connections create noise and reduce trust in the link graph
• A well-explained single link beats two tenuous ones

When adding links, explain the relationship:

• [[note]] - Same author explores this from a different angle
• [[note]] - Provides the theoretical foundation for these ideas

Phase 5: Quality Validation

Spawn parallel validators:

Wiki-link note: Readwise highlights (content/readwise/) are excluded from Nuxt Content and won't resolve as valid wiki-links. Use plain text or italics for books/articles that only exist in Readwise.

IF issues found: Use the AskUserQuestion tool:

question: "Validation found issues. How should I proceed?"
header: "Validation"
multiSelect: false
options:
  - label: "Fix issues"
    description: "Let me fix the issues before saving"
  - label: "Save anyway"
    description: "Proceed despite validation warnings"
  - label: "Cancel"
    description: "Don't save the note"

IF no issues: Log "✓ Validation passed" and proceed.

Phase 6: Save Note

Generate slug inline: lowercase title, replace spaces with hyphens, remove special characters. Example: "Superhuman Is Built for Speed" → superhuman-is-built-for-speed

Save to content/{slug}.md. Confirm with link density status:

✓ Note saved: content/{slug}.md
  - Type: {type}
  - Authors: {author-slugs}
  - Tags: {tag-count} tags
  - Wiki-links: {link-count} connections ({status})
    - [[link-1]] (why: {context})
    - [[link-2]] (why: {context})

Link density status:

• {link-count} >= 3: "well-connected"
• {link-count} = 1-2: "connected"
• {link-count} = 0: "standalone" (fine when no genuine connections exist)

Phase 7: MOC Placement (Non-blocking)

7.1 Suggest Existing MOC Placement

python3 .claude/skills/moc-curator/scripts/cluster-notes.py --mode=for-note --note={slug}

If suggestions score >= 0.7, present to user. Apply selections to MOC's ## Suggested section.

7.2 Check MOC Creation Threshold

After saving, check if any of the note's tags exceed the threshold:

# For each tag on the new note, count notes with that tag
Grep pattern: "tags:.*{tag}" glob: "content/*.md" output_mode: "count"

IF tag count >= 15 AND no existing MOC for that tag:

question: "The tag '{tag}' now has {count} notes. Would you like to create a MOC?"
header: "MOC Opportunity"
multiSelect: false
options:
  - label: "Create MOC"
    description: "Generate a '{tag}' guide/roadmap to organize these notes"
  - label: "Skip for now"
    description: "Don't create a MOC yet"

If "Create MOC" selected: Invoke moc-curator skill with --mode=new-clusters --tag={tag}.

Phase 8: Quality Check

Run linter and type check to catch any issues:

pnpm lint:fix && pnpm typecheck

If errors are found, fix them before completing the task.

Error Handling

Reference Files