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:

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 0: Load SOUL.md → Read SOUL.md for voice, perspective, and anti-patterns
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 + SOUL.md voice, 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 0: Load Soul (REQUIRED)

Read SOUL.md from the project root. This defines Alexander's voice, what he values in notes, anti-patterns to avoid, and how to add his perspective. Every note must reflect this identity — not just summarize a source.

Key things SOUL.md controls:

• Voice: Direct, opinionated, no filler — not polished AI prose
• Perspective: Always contextualize why Alexander cares about this content
• Author preservation: Don't flatten unique voices into generic summaries
• Anti-patterns: No sycophancy, no rigid same-template-for-everything, no generic summaries

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 URL ends in .pdf: WebFetch cannot parse PDFs. Use get-pdf-text.sh URL to download and extract text, then read the output file. For large PDFs (>50KB extracted text), use a subagent per Phase 2.5 pattern.

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:

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. Verify SOUL.md loaded (REQUIRED): Must have been read in Phase 0. If not, Read SOUL.md now
2. Load writing-style skill (REQUIRED): Read .claude/skills/writing-style/SKILL.md
3. Load linking philosophy (REQUIRED): Read .claude/skills/adding-notes/references/linking-philosophy.md
4. If isTechnical: collect code snippets from Phase 2
5. Compile frontmatter using template from content-type file
6. Generate body applying SOUL.md voice — add Alexander's perspective, preserve author's unique voice, no generic summaries (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 — Visual-First)

Alexander is a visual learner. Default to adding a diagram. Only skip when the content is genuinely too brief or structureless (short quotes, link lists).

1. Load references/diagrams-guide.md — apply the decision tree (all 7 triggers) with visual-first bias
2. If diagram needed (expected for most notes), delegate to the mermaid skill: a. Load mermaid skill: Read .agents/skills/mermaid/skill.md b. Choose the best diagram type — prefer mindmap for concept overviews, flowchart for processes c. Write diagram source to {slug}.mmd in project root d. Validate: .agents/skills/mermaid/tools/validate.sh {slug}.mmd e. If validation fails, fix syntax errors and re-validate f. Show ASCII preview output to user g. Copy validated mermaid block into note wrapped with MDC syntax:
   markdownCopy

   ::mermaid
   <pre>
   {validated mermaid source}
   </pre>
   ::
   

   h. Delete the .mmd file: command rm {slug}.mmd (use command to bypass shell aliases) i. For rich content (books, talks, long articles): consider a second diagram if there's both a concept overview AND a distinct process/framework
3. Log outcome (REQUIRED):
   • Adding: ✓ Diagram added: [mermaid-type] - [description]
   • Skipping: ✓ No diagram needed: [specific reason] (should be rare)

Phase 4.5: Connection Discovery

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

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:

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:

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