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.

URL Pattern	Type	Reference
youtube.com	See YouTube Classification	references/content-types/youtube.md or talk.md or podcast.md
reddit.com	reddit	references/content-types/reddit.md
github.com	github	references/content-types/github.md
goodreads.com/series/	manga	references/content-types/manga.md
goodreads.com, amazon.com (books)	book	references/content-types/book.md
spotify.com/episode, podcasts.apple.com	podcast	references/content-types/podcast.md
udemy.com, coursera.org, skillshare.com	course	references/content-types/course.md
.substack.com/p/, .beehiiv.com/p/, buttondown.email/*	newsletter	references/content-types/newsletter.md
Other URLs	article	references/content-types/article.md
No URL	note	references/content-types/note.md
Manual: quote	quote	references/content-types/quote.md
Manual: evergreen	evergreen	references/content-types/evergreen.md
Manual: map	map	references/content-types/map.md

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:

Script	Purpose
get-youtube-metadata.sh URL	Fetch video title, channel
get-youtube-transcript.py URL	Fetch video transcript
get-podcast-transcript.py [opts]	Multi-source podcast transcript
get-reddit-thread.py URL --comments N	Fetch thread and top comments
get-goodreads-metadata.sh URL	Fetch book title, author, cover
get-manga-metadata.sh URL	Fetch series metadata
get-github-metadata.sh URL	Fetch repo name, stars, language
find-related-notes.py FILE --limit N	Find semantically related notes

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:

Result	Action
Exact match found	Use the existing author's slug
Partial match	Read matched files, use AskUserQuestion to verify
No matches	Create new author (see below)

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:

Validator	Checks
Wiki-link exists	Each [[link]] exists in content/ (excluding Readwise)
Link context	Each link has adjacent explanation (not bare "See also")
Duplicate	Title/URL doesn't already exist
Tag	Tags match or similar to existing
Type-specific	E.g., podcast: profile exists, guest not in hosts

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

Error	Recovery
Metadata agent fails	Prompt for manual entry or WebFetch fallback
Transcript unavailable	Note "No transcript available" in body
Author not found online	Create minimal profile (name only)
Reddit 429	Wait 60s and retry
Semantic analysis timeout	Proceed without wiki-link suggestions
Validation crash	Warn user, recommend manual check

---

Reference Files

File	Purpose
references/author-creation.md	Author profile workflow
references/diagrams-guide.md	When/how to add mermaid diagrams
references/code-extraction.md	Technical content code snippets
references/podcast-profile-creation.md	Creating podcast show profiles
references/newsletter-profile-creation.md	Creating newsletter publication profiles
references/content-types/*.md	Type-specific templates and handling