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.

references/content-types/youtube.md

talk.md

podcast.md

references/content-types/reddit.md

references/content-types/github.md

references/content-types/movie.md

references/content-types/manga.md

references/content-types/book.md

references/content-types/podcast.md

references/content-types/course.md

references/content-types/newsletter.md

references/content-types/article.md

references/content-types/note.md

quote

references/content-types/quote.md

evergreen

references/content-types/evergreen.md

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

Scripts Reference

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

get-youtube-metadata.sh URL

get-youtube-transcript.py URL [--format FORMAT]

get-podcast-transcript.py [opts]

get-reddit-thread.py URL --comments N

get-goodreads-metadata.sh URL

get-manga-metadata.sh URL

get-github-metadata.sh URL

find-related-notes.ts FILE [--limit N] [--min-score N]

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

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

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

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

1. Fetch with sentences format:

   get-youtube-transcript.py URL --format sentences > transcript.txt

2. Read first 100 lines (intro, episode overview)
3. Read last 100 lines (conclusion, wrap-up)
4. Grep for key terms mentioned in intro
5. Extract quotes around grep matches with

   -C 3

   context

Benefits of Subagent Approach:

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

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)

Tags: 3-5 relevant tags. Use tags you've seen in prior notes or

Grep

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

Phase 4.25: Diagram Evaluation (REQUIRED)

1. Load

   references/diagrams-guide.md

2. Apply the decision tree based on content type priority
3. 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

1. Same-author check (highest priority):

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

2. Tag-based discovery:

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

3. 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:

[[link]]

content/

Wiki-link note: Readwise highlights (

content/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

✓ 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]

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

1. Suggest existing MOC placement via cluster script
2. 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

Reference Files

references/author-creation.md

references/diagrams-guide.md

references/linking-philosophy.md

references/moc-placement.md

references/code-extraction.md

references/podcast-profile-creation.md

references/newsletter-profile-creation.md

references/content-types/*.md