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

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 5: Quality Validation → 4 parallel validators (BLOCKING)
Phase 6: Save Note → Write to content/{slug}.md
Phase 7: MOC Placement → Suggest placements (non-blocking)
Phase 8: Quality Check → Run pnpm lint:fix && pnpm typecheck

Phase 1: Type Detection & Dispatch

1. Run generate-frontmatter.sh "[URL]" to auto-detect type
2. Load the content-type reference file for detailed handling
3. Start background semantic analysis agent:

   Task: "Run python3 scripts/find-related-notes.py content/TEMP.md --limit 10"
   run_in_background: true
   

4. 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. Run check-author-exists.sh for each author.

Handle by result:

For POSSIBLE_MATCH, 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. Generate with generate-author-frontmatter.sh
4. Save to content/authors/{slug}.md

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. Collect semantic analysis results from Phase 1
3. If isTechnical: collect code snippets from Phase 2
4. Compile frontmatter using template from content-type file
5. Generate body with wiki-links for strong connections only
6. Add diagrams if applicable (see references/diagrams-guide.md)

Tags: 3-5 relevant tags, check existing: list-existing-tags.sh

Wiki-links: Link only when same author, explicit reference, same core topic, or same series. When in doubt, leave it out.

Phase 5: Quality Validation (BLOCKING)

Spawn 4 parallel validators:

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

.claude/skills/adding-notes/scripts/generate-slug.sh "Title"

Save to content/{slug}.md. Confirm:

✓ Note saved: content/{slug}.md
  - Type: {type}
  - Authors: {author-slugs}
  - Tags: {tag-count} tags
  - Wiki-links: {link-count} connections

Phase 7: MOC Placement (Non-blocking)

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.

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