obsidian-notes-creator

어떤 스킬인가요?

Create high-quality Obsidian study notes with rich analogies, diagrams, and structured explanations. Handles both single notes and multi-file topic sets. Use when creating study notes, summarising lecture content, building a knowledge base, or organising any learning material into Obsidian markdown. Triggers - create study notes, obsidian notes, study notes, organise notes, learning notes, note from lecture, note from PDF.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Callouts Reference

Obsidian callouts are blockquotes with a type tag. They render with a coloured border, icon, and title.

## Syntax

```markdown
> [!type] Optional custom title
> Content line 1
> Content line 2
```

Foldable — add `-` (collapsed by default) or `+` (expanded, collapsible):
```markdown
> [!faq]- Click to expand
> Hidden until clicked.
```

Nested:
```markdown
> [!note] Outer
> > [!warning] Inner
> > Nested content
```

---

## All 13 Types — When to Use Each

| Type | Aliases | Colour | Use when… |
|---|---|---|---|
| `note` | — | Blue | Background context, extra info, "by the way" facts |
| `info` | — | Blue | Defining terms, clarifying scope |
| `abstract` | `summary`, `tldr` | Teal | Opening 1-sentence summary of a long section |
| `tip` | `hint`, `important` | Cyan | Best practices, shortcuts, "remember this" |
| `success` | `check`, `done` | Green | Confirming correct understanding, "this is the right way" |
| `question` | `help`, `faq` | Yellow | Posing exam-style questions inside the note |
| `warning` | `caution`, `attention` | Orange | Common mistakes, subtle gotchas, "don't confuse with…" |
| `failure` | `fail`, `missing` | Red | What breaks, what doesn't work, anti-patterns |
| `danger` | `error` | Red | Critical misunderstandings that cause wrong answers |
| `bug` | — | Red | Known edge cases or counterintuitive behaviours |
| `example` | — | Purple | Analogies, worked examples, concrete illustrations |
| `quote` | `cite` | Grey | Direct quotes from papers, textbooks |
| `todo` | — | Blue | Study tasks, things to revisit |

---

## Decision Guide

```
Is this a mistake students commonly make?       → [!warning] or [!danger]
Is this a concrete example or analogy?          → [!example]
Is this a "remember this" shortcut?             → [!tip]
Is this background context, not core content?   → [!note]
Is this a self-check question?                  → [!question]
Is this a paper quote?                          → [!quote]
Is this confirming correct reasoning?           → [!success]
```

---

## Anti-patterns to Avoid

- **Don't wrap normal paragraphs in callouts** just to add colour. Callouts should signal something special.
- **Don't use `[!note]` for everything** — it dilutes meaning. Pick the most specific type.
- **Don't make callouts too long.** If it's more than ~6 lines, it's probably main content, not a callout.

---

## Examples

### Marking a common mistake
```markdown
> [!warning] Don't confuse these
> The **key encoder** in MoCo is NOT updated by backprop.
> Only the query encoder is. The key encoder uses momentum averaging.
```

### Analogy block
```markdown
> [!example] Shoebox analogy
> Think of the queue as a shoebox of ID cards.
> Each batch adds new cards. Old cards stay until the box is full.
> The momentum encoder ensures all cards were taken with the same camera.
```

### Foldable practice question
```markdown
> [!question]- Why does MAE use 75% masking instead of 15%?
> Images are spatially redundant — neighbours are highly correlated.
> 15% masking is too easy; the model just copies adjacent pixels.
> 75% forces reasoning about global object structure.
```

# Diagrams Reference

Two tools: **Mermaid** (preferred) and **ASCII** (for cases Mermaid can't handle).

---

## Mermaid — Which Type to Use

| Diagram type | Use when… | Avoid when… |
|---|---|---|
| `flowchart LR/TB` | Process flow, decision trees, cause → effect | Showing time order between actors |
| `sequenceDiagram` | Two or more actors exchanging messages over time | Simple one-actor process |
| `stateDiagram-v2` | Lifecycles, phases, state machines | Things without clear states |
| `mindmap` | Topic overview, brainstorming, classification trees | Processes with order |
| `timeline` | Historical events, evolution of a concept | Non-time-ordered things |
| `flowchart TB` (tree) | Hierarchies, taxonomies, "A is a type of B" | Cyclic relationships |

---

## Mermaid Templates

### Flowchart — Process / Decision
```mermaid
flowchart LR
    A[Start] --> B{Decision?}
    B -->|Yes| C[Path A]
    B -->|No| D[Path B]
    C --> E[End]
    D --> E
```

### Flowchart TB — Hierarchy / Taxonomy
```mermaid
flowchart TB
    A[Parent] --> B[Child A]
    A --> C[Child B]
    B --> D[Leaf 1]
    B --> E[Leaf 2]
```

### Sequence Diagram — Actors Exchanging Messages
```mermaid
sequenceDiagram
    participant Q as Query Encoder
    participant K as Key Encoder
    participant L as Loss
    Q->>L: query vector
    K->>L: key vectors (from queue)
    L-->>Q: gradient (backprop)
    L-..->K: no gradient (momentum only)
```

### State Diagram — Lifecycle / Phases
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Training : start
    Training --> Converged : loss stable
    Training --> Failed : diverged
    Converged --> [*]
```

### Mind Map — Topic Overview
```mermaid
mindmap
  root((Topic))
    Branch A
      Detail 1
      Detail 2
    Branch B
      Detail 3
```

### Timeline — Historical / Evolution
```mermaid
timeline
    title Evolution of SSL
    2016 : Context Encoders
    2018 : BERT (NLP)
    2020 : MoCo · SimCLR
    2022 : MAE
```

---

## Multi-line Node Labels

Use backtick strings for multi-line text inside nodes:

```mermaid
flowchart LR
    A["`key encoder
    slow update`"] --> B["`queue
    65k negatives`"]
```

---

## ASCII Diagrams — When to Use

Use ASCII **only** when:
- You need a **custom layout** that Mermaid can't express (e.g., showing a fraction, a queue buffer, a training loop state)
- You want to show **before vs. after** side by side
- You need to annotate specific parts of a diagram with arrows mid-content

### Box Characters Reference
```
Corners:   ┌ ┐ └ ┘
Lines:     ─ (horizontal)   │ (vertical)
T-joints:  ├ ┤ ┬ ┴   Cross: ┼
Arrows:    → ← ↑ ↓   ▶ ◀ ▲ ▼
Double:    ═ ║ ╔ ╗ ╚ ╝
```

### Overview Box
```
┌─────────────────────────────────────────┐
│              TOPIC TITLE                │
├─────────────────────────────────────────┤
│  Concept A     Concept B     Concept C  │
│     │              │             │      │
│  [detail]       [detail]      [detail]  │
└─────────────────────────────────────────┘
```

### Layer / Stack
```
┌─────────────────────────────────────────┐
│              Top Layer                  │
├─────────────────────────────────────────┤
│              Middle Layer               │
├─────────────────────────────────────────┤
│              Bottom Layer               │
└─────────────────────────────────────────┘
```

### Queue / Buffer
```
Front                                  Back
  ↓                                     ↓
[k_1][k_2][k_3][ ... ][k_N]   ← FIFO queue
  ↑ dequeue                    enqueue ↑
(oldest removed)              (newest added)
```

### Before / After Contrast
```
WITHOUT momentum:                WITH momentum:
  Encoder v1  →  z_A (valid)      Encoder v1.000 → z_A (valid)
  [big update]                    [tiny update: Δ=0.001]
  Encoder v2  →  z_B              Encoder v1.001 → z_B (still ~valid)
  z_A vs z_B: INCOMPARABLE        z_A vs z_B: COMPARABLE
```

---

## Embedded Visuals — SVG / PNG (data Mermaid can't draw)

Mermaid and ASCII show **structure**. For **data with values** — heatmaps, charts,
confusion matrices, annotated figures — generate a self-contained **SVG** (or PNG)
and embed it. Renders natively in Obsidian, no plugin.

```
![[my-figure.svg|580]]      ← the |580 sets display width in px
```

Save figures to an assets folder (e.g. `99-assets/`). **Interactive JS does not
render** in Obsidian — always export a static image.

### Which tool for which visual
| Need | Tool |
|---|---|
| Process / hierarchy / lifecycle | Mermaid |
| Custom layout, before/after | ASCII or SVG |
| **Values + colour** (heatmap, chart, matrix) | **SVG / PNG** |
| Equations | LaTeX `$...$`, `$$...$$` |

### Dark/light-mode rules (Obsidian won't recolour your SVG)
- Transparent background — never paint a white/black rect.
- Labels/axes in **mid-grey `#8a8a8a`** — readable on any theme (never `#333` or `#fff`).
- Text on a coloured shape: white on dark tiles, near-black on light —
  `'#fff' if 0.299*r+0.587*g+0.114*b < 140 else '#1f1f1f'`.

### Generator skeleton
```python
W, H = 640, 400
svg = [f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {W} {H}" font-family="sans-serif">']
# append <rect>/<text>/<line>/<path> elements …
svg.append('</svg>')
open("99-assets/figure.svg", "w").write("\n".join(svg))
```

Pair every embedded figure with one sentence of prose naming **what to notice**.

---

## Mermaid Pitfalls — what breaks rendering

| Mistake | Why it breaks | Fix |
|---|---|---|
| `\n` in a label | Mermaid prints `\n` literally — no line break | keep the label on one line, or use the backtick multiline form |
| Numbered prefix `A[1. Step]` | the `1.` confuses the parser → error or blank diagram | drop the dot (`Step 1`), or quote it: `A["1. Step"]` |
| Special chars `( ) : ; # ,` in a label | unbalanced/illegal tokens | quote the whole label: `A["f(x): cost"]` |
| Brackets/quotes inside a label | parser sees them as syntax | quote the label, escape inner quotes |

> Rule of thumb: if a node label has anything beyond **letters, spaces, and a
> hyphen**, wrap it in `"…"` — and never number nodes with `1.` / `2.`.

# Frontmatter Reference

Obsidian reads YAML frontmatter at the top of every note (between `---` delimiters).
It powers search, dataview queries, and the Properties panel.

---

## Standard Block

```yaml
---
tags:
  - subject/topic
  - concept
date: YYYY-MM-DD
---
```

Always include at minimum: `tags` and `date`.

---

## All Property Types

| Type | YAML syntax | Example |
|---|---|---|
| Text | `key: value` | `status: in-progress` |
| Number | `key: 4.5` | `difficulty: 3` |
| Checkbox | `key: true` | `reviewed: false` |
| Date | `key: 2024-01-15` | `date: 2024-06-11` |
| Date + Time | `key: 2024-01-15T14:30:00` | `due: 2024-06-30T23:59:00` |
| List (inline) | `key: [a, b, c]` | `tags: [cv, ssl, moco]` |
| List (block) | multiline under key | see below |
| Link | `key: "[[Other Note]]"` | `related: "[[18-repr]]"` |

### Block list syntax
```yaml
tags:
  - CV
  - contrastive-learning
  - MoCo
```

---

## Recommended Tags Pattern

Use **hierarchical tags** with `/` to namespace by subject:

```yaml
tags:
  - CV/concepts          # subject / folder-type
  - CV/contrastive       # subject / sub-topic
  - exam-prep            # cross-subject utility tag
```

---

## Full Example

```yaml
---
tags:
  - CV/concepts
  - self-supervised-learning
  - contrastive-learning
date: 2026-06-11
status: complete
difficulty: 3
prerequisites:
  - "[[18-representation-learning]]"
---
```

---

## Notes

- Frontmatter **must be the first thing** in the file — no blank lines before the opening `---`.
- Obsidian treats unknown keys as custom properties — they won't break anything.
- `aliases` lets other notes link using different names: `aliases: ["SSL", "Self-Supervised"]`

# Wikilinks & Embeds Reference

---

## Basic Link Forms

```markdown
[[Note Name]]                    Link to a note by name
[[Note Name|Display Text]]       Link with custom label
[[Note Name#Heading]]            Link to a specific heading
[[Note Name#Heading|Label]]      Link to heading with custom label
[[#Heading in same note]]        Anchor link within the same note
[[Note Name#^block-id]]          Link to a specific block
```

---

## Embeds (Inline Transclusion)

```markdown
![[Note Name]]                   Embed entire note
![[Note Name#Heading]]           Embed from a heading downward
![[Note Name#^block-id]]         Embed a single block
![[image.png]]                   Embed an image
![[image.png|300]]               Embed image at 300px width
```

---

## Block References

Add a block ID at the end of a paragraph to make it linkable:

```markdown
The momentum encoder update ensures consistency across queue entries. ^moco-momentum

Then link to it elsewhere:
See [[19-self-supervised-learning#^moco-momentum]]
```

---

## When to Add Wikilinks

| Situation | Do this |
|---|---|
| Mentioning a concept covered in another note | `[[note-name\|concept name]]` |
| Referencing a prerequisite at the top | List under **Prerequisites:** heading |
| Referencing follow-up material | List under **Related:** heading |
| Embedding a shared diagram or table | `![[shared-note#diagram-section]]` |

---

## Linking Strategy for Study Notes

Every note should have at minimum:

```markdown
**Prerequisites:** [[prior-concept]] — why you need it
**See also:** [[related-technique]] — where this leads
```

And a **Related** section at the bottom:
```markdown
## Related

- [[prior-concept]] — foundation for this topic
- [[next-concept]] — builds on this
- [[example-note]] — worked examples
```

---

## Path Resolution

Obsidian resolves links by note name, not file path.
You don't need to write the full path — just the filename (without `.md`):

```markdown
[[19-self-supervised-learning]]       ✓ works
[[UM/CV/concepts/19-self-supervised-learning]]  ✓ also works (explicit)
```

Use explicit paths only when two notes share the same name.

# Quality Checklist

Run through this before closing a note or note set.

---

## Content Quality

- [ ] Every concept opens with **motivation** (what problem does it solve?) before the definition
- [ ] Every hard concept has an **analogy** — check `writing/analogies.md` for patterns
- [ ] Every concept has **at least one concrete example** — check `writing/examples.md`
- [ ] Formulas are accompanied by a **plain-English breakdown** (what each symbol means)
- [ ] Mathematical direction changes (negative signs, logs, inverses) are **explicitly walked through**
- [ ] Comparisons between similar concepts are **in a table**, not buried in prose

## Visual Quality

- [ ] Every note has **at least one Mermaid diagram** (flowchart, sequence, mindmap, etc.)
- [ ] Complex processes have an **ASCII before/after** or **queue/buffer diagram** if Mermaid can't express it
- [ ] Diagrams have labels that a reader can understand without reading the surrounding text

## Obsidian Components

- [ ] Callouts are used for: warnings, tips, analogies, practice questions — **not for decoration**
- [ ] Each callout type is used correctly (see `components/callouts.md` decision guide)
- [ ] Frontmatter is filled: `tags` and `date` at minimum
- [ ] At least **one wikilink** to a related or prerequisite note
- [ ] The **Related** section at the bottom has descriptions, not bare wikilinks

## Structure

- [ ] If the note is > ~400 lines, consider whether it should be **split** (see `structure/multi-file.md`)
- [ ] If split across files: a **hub/index note** exists and links to all sub-files
- [ ] Files are **numbered** for reading order if order matters
- [ ] The note opens with a **one-sentence summary** ("In a nutshell: …")

## Study Utility

- [ ] A **Common Pitfalls** or **Exam Pitfalls** table is included for exam-relevant topics
- [ ] Practice questions use **foldable callouts** (`> [!question]-`) so answers are hidden by default
- [ ] A **Summary Table** exists for topics with multiple terms or methods

---

## Minimum Viable Note

If time is short, at minimum a note must have:

1. One-sentence summary
2. One diagram (Mermaid)
3. One analogy or concrete example per major concept
4. Frontmatter with tags + date
5. At least one wikilink

# Index Note Template

The index (or hub) note is the entry point for a multi-file topic.
It doesn't contain detailed content — it provides orientation and navigation.

---

## Template

```markdown
---
tags:
  - subject/topic
  - index
date: YYYY-MM-DD
---

# [Subject Name]

> [Brief 2-3 sentence description of what this topic covers and why it matters.]

---

## Quick Navigation

### Core Concepts
- [[concepts/01-overview|Overview]] — Big picture and motivation
- [[concepts/02-concept-a|Concept A]] — [One-line description]
- [[concepts/03-concept-b|Concept B]] — [One-line description]

### Techniques & Methods
- [[techniques/01-method-a|Method A]] — [One-line description]

### Worked Examples
- [[examples/01-basic|Basic Examples]] — Start here
- [[examples/02-advanced|Advanced Examples]] — After concepts

### Practice
- [[practice/01-exercises|Exercises]] — Self-test questions

---

## Concept Map

[Mermaid diagram showing how the sub-topics relate to each other]

---

## Prerequisites

- [[prior-subject-note]] — [what the reader needs first]

---

*Last updated: YYYY-MM-DD*
```

---

## Rules for a Good Index Note

1. **No detailed content** — the index sets direction, not substance. If you're explaining something at length, it belongs in a concept file.
2. **Every link has a one-line description** — bare wikilinks are useless for navigation.
3. **The concept map is mandatory** — it shows structure at a glance.
4. **Prerequisites are explicit** — don't assume the reader knows what to read first.
5. **Last-updated date** — so you know when to review.

---

## When to Write the Index Note

Write it **last**, after all the concept/technique/example notes exist.
The index is a map of what you built — you can't map it until it exists.

Exception: if the topic is large enough, write a skeleton index first to plan the file structure, then fill it in as you write each sub-note.

# Multi-File Structure

Some topics are too large or too interconnected to fit in one note.
This file defines **when to split** and **how to organise** across multiple files.

---

## When to Split Into Multiple Files

Split when **any** of these apply:

1. **Length** — the note exceeds ~400 lines and still feels dense
2. **Reusability** — a sub-concept is referenced from multiple other notes (it deserves its own file so others can wikilink directly to it)
3. **Distinct audiences** — one part is conceptual theory, another is step-by-step technique, another is worked examples. Different readers want different parts.
4. **Natural subtopics** — the topic has 3+ major sub-concepts that each warrant their own diagram and examples

Do **not** split just because a topic is "big". Split when the parts are genuinely separable.

---

## Standard Folder Layout

```
topic-name/
├── README.md                  ← Hub/index note (see structure/index-note.md)
├── concepts/                  ← Theory and "what is X"
│   ├── 01-overview.md
│   ├── 02-concept-a.md
│   └── 03-concept-b.md
├── techniques/                ← "How to do X" — algorithms, methods, procedures
│   ├── 01-method-a.md
│   └── 02-method-b.md
├── examples/                  ← Worked problems and case studies
│   ├── 01-basic.md
│   └── 02-advanced.md
└── practice/                  ← Exercises, past exam questions
    └── 01-exercises.md
```

Not all folders are required. Use only what the topic needs:
- A pure theory topic might only need `concepts/`
- A procedural topic might only need `concepts/` + `techniques/`
- A problem-solving topic might only need `concepts/` + `examples/` + `practice/`

---

## File Naming Conventions

- **Prefix with numbers** for reading order: `01-`, `02-`, `03-`
- **Use kebab-case**: `self-supervised-learning.md` not `selfSupervisedLearning.md`
- **Name after the concept**, not after what it contains: `moco.md` not `momentum-encoder-notes.md`
- **Keep names short**: the folder provides context

---

## Cross-File Linking

Every file in a multi-file structure should:
1. Link back to the hub: `← [[README]]`
2. Link forward to the next logical file
3. Use `![[file#section]]` to embed shared content rather than copy-pasting

Example top-of-file navigation:
```markdown
**Topic:** [[README|Self-Supervised Learning]]
**Previous:** [[01-overview]]
**Next:** [[03-simclr]]
```

---

## Deciding File Granularity

| Situation | Decision |
|---|---|
| Two concepts are always explained together | Keep in one file, use `##` headings |
| One concept is referenced from 3+ other notes | Give it its own file |
| A concept has its own diagram, examples, and pitfalls | Give it its own file |
| A concept is just a definition (< 10 lines) | Keep in a parent file, use `###` heading |

---

## Example: Self-Supervised Learning

This topic naturally splits because contrastive and predictive learning are distinct families, and MoCo/SimCLR/MAE each have enough depth for their own files:

```
CV/
├── README.md
├── concepts/
│   ├── 01-classical-unsupervised.md    ← K-means, PCA, Autoencoder
│   ├── 02-contrastive-learning.md      ← Framework + InfoNCE loss
│   ├── 03-moco.md                      ← Queue + momentum encoder
│   ├── 04-simclr.md                    ← Single encoder, large batch
│   └── 05-mae.md                       ← Masking, ViT, 75% ratio
└── practice/
    └── 01-ssl-exercises.md
```

# Single Note Template

Use this template when a topic fits comfortably in one file (roughly under 400 lines).

---

## Full Template

```markdown
---
tags:
  - subject/topic
date: YYYY-MM-DD
---

# [Topic Title]

> **In a nutshell:** One sentence. What is this and why does it matter?

**Prerequisites:** [[prior-concept]] — what the reader needs to know first
**See also:** [[related-note]] — where this leads next

---

## Overview

[Mermaid or ASCII diagram showing the big picture of this topic]

---

## [Section 1: Main Concept]

[Problem / motivation — what goes wrong without this?]

[Intuition — plain language, no symbols]

> [!example] [Analogy title]
> [Concrete analogy using Pattern 1–5 from writing/analogies.md]

[Formal definition or formula]

**Breaking it down:**
| Symbol / Part | Meaning |
|---|---|
| ... | ... |

**Why it works:** [Connect the formula back to the intuition]

---

## [Section 2: Mechanism / Algorithm]

[Step-by-step with a diagram if helpful]

```
Step 1: [action]
Step 2: [action]
Result: [outcome]
```

---

## [Section 3: Comparison (if applicable)]

| Dimension | This | Alternative |
|---|---|---|
| ... | ... | ... |

**Key difference:** [One sentence summary]

---

## Summary Table

| Term | Definition | Example |
|---|---|---|
| [concept] | [brief] | [concrete] |

---

## Common Pitfalls

| Pitfall | Correct understanding |
|---|---|
| "[wrong belief]" | [correct explanation] |

---

## Practice

1. [Question]
   > [!question]- Answer
   > [Step-by-step answer]

2. [Question]
   > [!question]- Answer
   > [Answer]

---

## Related

- [[note-a]] — [why it's related]
- [[note-b]] — [why it's related]
```

---

## Notes on the Template

- The **overview diagram** is mandatory. If you can't draw it in Mermaid, use ASCII.
- The **in-a-nutshell** line forces you to understand the concept before writing about it.
- **Common Pitfalls** should reflect actual mistakes — don't fabricate them.
- **Practice** questions should use foldable callouts so the note can double as a study tool.
- **Related** links should always have a reason next to them, not just a bare wikilink.

# Analogy Patterns

Analogies are the most powerful tool for making abstract concepts click.
This file defines the **types** of analogies and **when to use each**.

---

## Rule: Analogy Before Formula

Always introduce the intuition with an analogy **before** showing the math or formal definition.
The analogy gives the student a mental hook; the formula gives it precision.

```
WRONG order:  Formula → Example → Analogy (analogy feels like an afterthought)
RIGHT order:  Analogy → Intuition → Formula → Confirmation
```

---

## Pattern 1: Step-Down Analogy

Start with a very everyday scenario, then progressively map each element to the technical concept.

**Structure:**
```
1. Everyday version (no jargon)
2. "This maps to X in our context"
3. Technical version (with jargon)
```

**Example — InfoNCE loss:**
> You're in a room with 1 friend and 99 strangers.
> Someone asks: "What fraction of the crowd's attention belongs to your friend?"
>
> - Loss is LOW when your friend clearly stands out (close to you, strangers are far).
> - Loss is HIGH when strangers crowd you equally — your friend is lost in the noise.
>
> The model is trained to maximise this fraction. That's exactly what the InfoNCE numerator/denominator does.

---

## Pattern 2: Before / After Contrast

Show what happens **without** the mechanism, then **with** it.
This makes the problem vivid before the solution lands.

**Structure:**
```
WITHOUT [mechanism]:
  [show the broken state — concrete steps]

WITH [mechanism]:
  [show the fixed state — same concrete steps, different outcome]
```

**Example — MoCo momentum encoder:**
```
WITHOUT momentum encoder:
  Step 1: Measure Alice with ruler v1 → 170 cm → save
          [Encoder updates — ruler changes a LOT]
  Step 2: Measure Bob with ruler v2  → 175 cm → save
  Q: Is Bob taller than Alice?
  A: Can't tell. Different rulers. Old data is USELESS.

WITH momentum encoder:
  Step 1: Measure Alice with ruler v1.000 → 170 cm → save
          [Ruler adjusts by 0.001 — almost nothing]
  Step 2: Measure Bob with ruler v1.001  → 175 cm → save
  Q: Is Bob taller than Alice?
  A: Yes — the ruler barely changed. Data is STILL VALID.
```

Use this pattern when: a mechanism exists to **solve a problem that only arises with scale or over time**.

---

## Pattern 3: Object Analogy

Map the abstract system to a physical object with a clear, visualisable structure.

**Structure:**
```
[Object] = [Technical thing]
[Part of object] = [Component of technical thing]
[Action on object] = [Operation in the system]
```

**Example — MoCo queue:**
> **The shoebox of ID cards**
>
> - The shoebox = the queue (stores past representations)
> - The ID card = the encoded representation vector of one image
> - Taking a photo = running an image through the key encoder
> - Removing the oldest card = FIFO dequeue
> - The camera settings = the momentum encoder (changes slowly so cards stay comparable)

Pairs well with Pattern 2 — use Pattern 3 to name the analogy, then Pattern 2 to show it in action.

---

## Pattern 4: Process-as-Pseudocode Analogy

When the concept is a sequential process, write it as pseudocode but using everyday words.
This bridges the gap between narrative and technical.

**Structure:**
```
Step 1: [everyday action]  →  [what this maps to technically]
Step 2: [everyday action]  →  [technical]
Result: [everyday outcome] →  [technical outcome]
```

**Example — Why autoencoder ≠ semantic understanding:**
```
ZIP two photos of the same person:
  compress(photo_A) → bits_A
  compress(photo_B) → bits_B

  bits_A ≠ bits_B   ← completely different compressed output
  decompress(bits_A) → photo_A   ✓ perfect reconstruction
  decompress(bits_B) → photo_B   ✓ perfect reconstruction

Conclusion: ZIP never learned they're the same person.
            It only learned to copy bytes efficiently.
            An autoencoder has exactly the same weakness.
```

---

## Pattern 5: Fraction / Direction Flip

For mathematical concepts involving a negative sign, log, or inverse, walk through the direction change explicitly.

**Structure:**
```
Minimize [expression]
  = Minimize -log(fraction)    ← negative sign flips goal
  = Maximize  log(fraction)    ← log is monotone, so...
  = Maximize      fraction     ← this is the real goal
```

Then explain what makes the fraction bigger (numerator ↑, denominator ↓).

---

## Choosing the Right Pattern

| Situation | Best pattern |
|---|---|
| Introducing a new formula | Pattern 5 (direction flip) or Pattern 1 (step-down) |
| Explaining why a mechanism exists | Pattern 2 (before/after contrast) |
| Describing a data structure / system component | Pattern 3 (object analogy) |
| Showing a process step-by-step | Pattern 4 (process-as-pseudocode) |
| General concept intuition | Pattern 1 (step-down) |

---

## Quality Signals for a Good Analogy

- A student with no domain knowledge can follow the analogy
- Every component of the analogy maps to something real in the system
- The analogy doesn't break down halfway through
- After reading it, the formula or definition feels "obvious" rather than arbitrary

# Comparison Patterns

When two or more things are related but different, comparisons prevent confusion and build deeper understanding. This file defines when and how to compare.

---

## Rule: Compare as Early as Possible

Don't wait until the end of a section to compare. If you're introducing B and A already exists in the notes, compare them immediately after introducing B.

---

## Pattern 1: Side-by-Side Table

The most common and readable format. Use whenever comparing 2+ things across multiple dimensions.

```markdown
| Dimension | Thing A | Thing B |
|---|---|---|
| [attribute 1] | ... | ... |
| [attribute 2] | ... | ... |
| [key difference] | ... | ... |
```

**Tips:**
- Put the **most important distinguishing row last** (it's what the student remembers)
- Use ✅ / ❌ for binary comparisons
- Keep cells short — one concept per cell

**Example:**
| | MoCo | SimCLR |
|---|---|---|
| Encoders | Two (query + key) | One (shared) |
| Key update | Momentum (no grad) | Backprop |
| Negative source | Queue of past keys | Current batch |
| Batch size needed | Moderate (256) | Large (4096+) |
| Memory cost | Queue | Large batch |

---

## Pattern 2: Hierarchy View

For things that are generalisations of each other. Show the progression from most constrained to most general.

```markdown
[Most specific / constrained]
  ↓  relaxes [constraint A]
[Middle]
  ↓  relaxes [constraint B]
[Most general]
```

**Example:**
```
K-means      encoder = hard assignment (one-hot),  decoder = lookup table
  ↓  relax: allow soft, continuous encoding
PCA          encoder = linear projection,           decoder = linear projection back,  + orthogonality constraint
  ↓  relax: allow nonlinear transforms + remove constraint
Autoencoder  encoder = deep NN,                    decoder = deep NN,                 no constraint
```

---

## Pattern 3: Similarities + Key Difference

After a table, always close with a plain-text summary of what they share and what truly separates them. The table shows details; this paragraph gives the mental model.

```markdown
**Similarities:** Both X and Y do [shared goal]. Both use [shared mechanism].

**Key difference:** X [does A] while Y [does B]. This matters because [consequence].
```

**Example:**
> **Similarities:** Both MoCo and SimCLR use the InfoNCE loss and data augmentation to create positive pairs.
>
> **Key difference:** MoCo decouples the number of negatives from batch size (via queue + momentum encoder), while SimCLR requires a huge batch to have enough negatives. This makes MoCo more memory-efficient for the same number of negatives.

---

## Pattern 4: Before / After (Same System, Different Config)

For comparing the same concept under different parameter settings.

```markdown
| Setting | What happens | Why |
|---|---|---|
| [param] too low | [failure mode] | [reason] |
| [param] optimal | [good outcome] | [reason] |
| [param] too high | [different failure] | [reason] |
```

**Example — Masking ratio in MAE:**
| Masking ratio | Transfer accuracy | Why |
|---|---|---|
| 10% (too low) | ~55% | Too easy — model copies neighbours |
| 75% (optimal) | ~75% | Forces global reasoning |
| 90% (too high) | ~66% | Too little context to reconstruct from |

---

## When Not to Use a Table

- When there's only **one** meaningful difference → use a sentence instead
- When the cells would be > 1 line each → split into separate sections with headers
- When the items are **not parallel** (different types of things) → tables imply they're comparable

# Example Patterns

Concrete examples are non-negotiable. Every concept needs at least one.
This file defines the **structures** for writing good examples in study notes.

---

## Pattern 1: Concept → Example → Variation

The most versatile pattern. Show the concept, apply it to a specific case, then twist one variable to deepen understanding.

```markdown
## [Concept Name]

**Definition:** [Brief explanation]

**Example:**
[Specific, concrete scenario with real numbers or names]

**Variation:**
What if [one thing changes]? → [Different outcome and why]
```

**Real instance:**
```markdown
## Osmosis

**Definition:** Water moves from low to high solute concentration across a semipermeable membrane.

**Example:**
A red blood cell placed in salt water (high solute outside) → water leaves the cell → cell shrinks (crenation).

**Variation:**
What if the cell is placed in pure water? → Water floods in → cell swells → may burst (lysis).
```

---

## Pattern 2: Problem → Solution → Why It Works

For algorithm steps, derivations, or exam-style problems.

```markdown
**Problem:** [Specific question or scenario]

**Solution:**
Step 1: [action]
Step 2: [action]
Result: [answer]

**Why it works:** [The underlying principle that makes each step correct]
```

Use a foldable callout for solutions when the note doubles as practice material:
```markdown
> [!question]- Solution
> Step 1: ...
> Step 2: ...
> Result: ...
```

---

## Pattern 3: Cross-Discipline Example Table

For concepts that appear across subjects. Shows transferability.

| Subject | Concept | Concrete Example | Variation |
|---|---|---|---|
| Biology | Osmosis | RBC in salt water → shrinks | In pure water → swells |
| Physics | Momentum | Bowling ball vs tennis ball, same speed | Same mass, different speed? |
| Economics | Supply/Demand | OPEC cuts oil → price rises | New oil discovered → price falls |
| ML | Contrastive loss | Positive pair pulled closer | Negative pair pushed apart |

---

## Pattern 4: Named Worked Example

For complex derivations or multi-step proofs, give the example a title so it's referenceable.

```markdown
### Example: Why momentum encoder is needed

Suppose the encoder updates by 10% per step (no momentum).

After batch 1: encode image A → z_A (with encoder v1)
After batch 2: encoder changes → z_B encoded with v2
...
After batch 100: z_A was encoded with a completely different network.
z_A and z_100 are not comparable → the queue is useless.

Conclusion: large encoder updates invalidate the queue.
```

---

## What Makes an Example Good

- **Specific** — uses actual names, numbers, or concrete scenarios (not "some X")
- **Short** — 3-6 lines; if longer, it's a worked problem, not an example
- **Directly follows the concept** — not relegated to a later section
- **Teaches something you couldn't see from the definition alone**
- **Has a variation** that either confirms or surprises

## What Makes an Example Bad

- Circular: "For example, contrastive loss contrasts positives and negatives" (just restates the definition)
- Too abstract: "For example, consider two vectors A and B" (no context)
- Too long: becomes its own mini-lecture without a clear point

# Intuition-First Writing

The most common mistake in study notes is leading with the formula, definition, or algorithm — before the student knows *why it exists* or *what problem it solves*. This file defines the order to build understanding.

---

## The Golden Order

```
1. Problem           — What goes wrong without this?
2. Intuition         — What's the big-picture idea?
3. Analogy           — Make it concrete (see writing/analogies.md)
4. Formal definition — Now the formula/algorithm lands
5. Confirmation      — "This is why the formula looks this way"
```

Never open a concept with its definition. Open with its **motivation**.

---

## Practical Templates

### For a new concept

```markdown
## [Concept Name]

> **In a nutshell:** One sentence that gives the core idea without jargon.

### The Problem It Solves

[What goes wrong in the world without this concept? 2-3 sentences.]

### Intuition

[Big-picture explanation using plain language. No symbols yet.]

### How It Works

[Now introduce the mechanism, formula, or algorithm.]

**Why the formula looks this way:**
[Connect each part of the formula back to the intuition.]
```

### For a formula

```markdown
## [Formula Name]

Plain-text version first:
"[What the formula computes in plain English]"

Formal version:
$$[formula]$$

Breaking it down:
| Part | Meaning |
|---|---|
| [symbol] | [what it represents] |

Why minimising/maximising this achieves the goal:
[Step through the direction, e.g. "The -log flips the goal: minimising -log(x) = maximising x"]
```

---

## Specific Patterns

### "Why does this formula push X and pull Y?"

Walk through in three lines:
```
Minimising L
  = Maximising the fraction        (negative log flips direction)
  Fraction grows when:
    numerator ↑  →  positive pair gets closer
    denominator ↓  →  negative pairs get pushed away
```

### "Why does this design choice exist?"

Open with the world **without** the design choice:
```
Without [X], the problem is: [concrete failure mode].
With [X], [concrete improvement].
```
Then explain the mechanism.

### "Why this number / threshold?"

Show what happens at too-low and too-high values:
```
[Parameter] too low  →  [failure mode A]
[Parameter] at optimum  →  [good outcome]
[Parameter] too high →  [failure mode B]
```
This works for masking ratio, temperature, momentum, learning rate, etc.

---

## Signals That Notes Are Formula-First (Bad)

- The first thing after the heading is a LaTeX block
- There's no "problem" or "motivation" section before the algorithm
- Examples appear only at the end, as an afterthought
- The student would need to already understand the concept to read the note

## Signals That Notes Are Intuition-First (Good)

- The first paragraph explains what the concept is trying to do
- An analogy appears before any symbols
- The formal definition comes with a "why it looks this way" explanation
- A student with no background could read the first 3 paragraphs and get the gist

---
name: obsidian-notes-creator
description: Create high-quality Obsidian study notes with rich analogies, diagrams, and structured explanations. Handles both single notes and multi-file topic sets. Use when creating study notes, summarising lecture content, building a knowledge base, or organising any learning material into Obsidian markdown. Triggers - create study notes, obsidian notes, study notes, organise notes, learning notes, note from lecture, note from PDF.
---

# Obsidian Notes Creator

Transform source material into genuinely excellent study notes — with analogies that make hard things click, diagrams that show structure at a glance, and layouts that scale from a single concept to an entire subject.

## Workflow

```mermaid
flowchart LR
    A[Source Material] --> B[Understand & Extract]
    B --> C{Single topic or multi-file?}
    C -->|Single| D[Write Note]
    C -->|Multi| E[Plan Structure]
    E --> D
    D --> F[Enrich with Components]
    F --> G[Quality Check]
```

---

## Step 1: Understand the Source

Read the source material and identify:
- The **core concepts** (theory, definitions, formulas)
- The **mechanisms** (how things work, algorithms, processes)
- The **tricky parts** (things a student would get confused by)
- Where **analogies and examples** would help most

The tricky parts are the most important — they're where the note earns its value.

---

## Step 2: Decide Scope

**Single note** (one `.md` file) when the topic is self-contained and under ~400 lines.
→ Use template in [`references/structure/single-note.md`](references/structure/single-note.md)

**Multi-file** when the topic has 3+ major sub-concepts, or when sub-concepts are reused by other notes.
→ See rules and folder layouts in [`references/structure/multi-file.md`](references/structure/multi-file.md)
→ Write a hub note last: [`references/structure/index-note.md`](references/structure/index-note.md)

---

## Step 3: Write Content

**Order matters.** Always: motivation → intuition → analogy → formal definition → confirmation.
Never open with a formula. See [`references/writing/intuition-first.md`](references/writing/intuition-first.md).

For every hard concept, choose an analogy pattern:
→ [`references/writing/analogies.md`](references/writing/analogies.md) — 5 patterns: step-down, before/after, object, pseudocode, direction-flip

For every concept, add at least one example:
→ [`references/writing/examples.md`](references/writing/examples.md) — Concept→Example→Variation, Problem→Solution→Why

When two things are similar, compare them immediately:
→ [`references/writing/comparisons.md`](references/writing/comparisons.md) — tables, hierarchy views, similarities + key difference

---

## Step 4: Add Obsidian Components

Use callouts to signal special content (warnings, analogies, tips, questions) — not for decoration:
→ [`references/components/callouts.md`](references/components/callouts.md) — all 13 types with a decision guide

Choose the right diagram type for the content:
→ [`references/components/diagrams.md`](references/components/diagrams.md) — Mermaid (6 types) + ASCII patterns + embedded SVG/PNG for data visuals

Fill frontmatter with tags and date:
→ [`references/components/frontmatter.md`](references/components/frontmatter.md)

Link related notes with wikilinks:
→ [`references/components/wikilinks.md`](references/components/wikilinks.md)

---

## Step 5: Quality Check

Before finishing, run through:
→ [`references/quality-checklist.md`](references/quality-checklist.md)

Key gates: every hard concept has an analogy, every concept has an example, every note has a diagram, callouts are used purposefully, frontmatter is filled.