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 | | imdb.com/title/, themoviedb.org/movie/ | movie | references/content-types/movie.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:

Known podcast channel? → references/content-types/podcast.md
Known talk channel OR conference title? → references/content-types/talk.md
Tutorial signals? → references/content-types/youtube.md with isTechnical: true
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 | Video title, channel | | get-youtube-transcript.py URL [--format FORMAT] | Video transcript (see formats below) | | get-podcast-transcript.py [opts] | Podcast transcript | | get-reddit-thread.py URL --comments N | Thread + comments | | get-goodreads-metadata.sh URL | Book metadata | | get-manga-metadata.sh URL | Manga series data | | get-github-metadata.sh URL | Repo stats | | find-related-notes.ts FILE [--limit N] [--min-score N] | Semantic search using project embeddings |

Transcript Format Options

get-youtube-transcript.py URL                      # plain (default) - single blob
get-youtube-transcript.py URL --format sentences   # one sentence per line (grep-friendly)
get-youtube-transcript.py URL --format timestamped # [MM:SS] per segment
get-youtube-transcript.py URL --format json        # full metadata with timestamps

Recommended: Use --format sentences for large transcripts—enables grep/search and chunked reading.

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

Author check: Glob with content/authors/*{lastname}*.md
Frontmatter: Write YAML directly
Tag lookup: Grep or knowledge from prior notes

Workflow Phases

Phase 1: Type Detection → Route to content-type file
Phase 2: Parallel Metadata Collection → Per-type agents
Phase 2.5: Large Transcript Handling → Subagent for >10K token transcripts
Phase 3: Author Creation → See references/author-creation.md
Phase 4: Content Generation → Apply writing-style, generate body
Phase 4.25: Diagram Evaluation → REQUIRED visual assessment with logged outcome
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

Detect type from URL using the Content Type Routing table above (no script needed)
Load the content-type reference file for detailed handling
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 2.5: Large Transcript Handling

For podcasts/videos with transcripts >10K tokens, use a dedicated subagent instead of reading directly.

Detection: If transcript file exceeds 50KB or initial read fails with token limit error.

Option A: Transcript Analysis Subagent (Recommended)

Spawn a Task with subagent_type: general-purpose:

Analyze this transcript and extract structured content for a knowledge base note.

**Instructions:**
1. Read the transcript file at: {transcript_path}
2. Extract and return:

## Timestamps
| Time | Topic |
|------|-------|
(Major topic shifts with approximate times)

## Key Arguments
(3-5 main claims with supporting reasoning, 2-3 sentences each)

## Notable Quotes
(4-6 verbatim quotes that capture core ideas, with speaker attribution)

## Named Frameworks
(Any models, principles, or processes given specific names)

## Diagram Candidates
(Any process, system, or framework worth visualizing)

**Output:** Structured markdown, max 1500 words.

Option B: Chunked Extraction (Fallback)

If subagent unavailable, use --format sentences and manual chunking:

Fetch with sentences format: get-youtube-transcript.py URL --format sentences > transcript.txt
Read first 100 lines (intro, episode overview)
Read last 100 lines (conclusion, wrap-up)
Grep for key terms mentioned in intro
Extract quotes around grep matches with -C 3 context

Benefits of Subagent Approach: | Aspect | Direct Read | Subagent | |--------|-------------|----------| | Context usage | Fills main context with raw text | Returns only structured output | | Parallelism | Sequential processing | Runs alongside other agents | | Semantic analysis | Manual grep for terms | Agent identifies themes | | Output quality | May miss connections | Comprehensive extraction |

Phase 3: Author Creation

For external content, check if author exists:

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

Match found: Use existing slug
Partial match: Use AskUserQuestion to confirm identity
No match: Create new author per references/author-creation.md

Phase 4: Content Generation

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

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.25: Diagram Evaluation (REQUIRED)

Load references/diagrams-guide.md
Apply the decision tree based on content type priority
Log outcome (REQUIRED):
- Adding: ✓ Diagram added: [mermaid-type] - [description]
- Skipping: ✓ No diagram needed: [specific reason]

Phase 4.5: Connection Discovery

Load references/linking-philosophy.md and follow the discovery checklist:

Same-author check (highest priority): Grep pattern: "authors:.*{author-slug}" glob: "content/*.md"
Tag-based discovery: Grep pattern: "tags:.*{tag}" glob: "content/*.md" limit: 5
Evaluate: "Would I naturally reference this when discussing the topic?"

Only add genuine connections with explanatory context. Orphans are acceptable.

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 AskUserQuestion to offer: Fix issues / Save anyway / Cancel. 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
  - Diagram: {diagram-status}
  - Wiki-links: {link-count} connections ({status})
    - [[link-1]] (why: {context})
    - [[link-2]] (why: {context})

Diagram status: Added: [type] - [description] or None: [reason]

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)

See references/moc-placement.md for detailed workflow:

Suggest existing MOC placement via cluster script
Check if any tag exceeds 15-note threshold for new MOC creation

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 | | Transcript too large (>10K tokens) | Use Phase 2.5 subagent or chunked extraction | | 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/linking-philosophy.md | Connection quality standards | | references/moc-placement.md | MOC suggestion and creation | | references/code-extraction.md | Technical content code snippets | | references/podcast-profile-creation.md | Podcast show profiles | | references/newsletter-profile-creation.md | Newsletter publication profiles | | references/content-types/*.md | Type-specific templates |