PKM — Claude instructions

This is a personal knowledge management vault (Obsidian-flavoured Markdown).

Remote

The only remote is gitlab. Never use GitHub or origin.
Push to gitlab and update the GitLab MR after every batch of changes.

Vault structure

2 - Areas/
  About Me/           # Personal profile and learning goals
  Finance/            # Market microstructure, derivatives, credit risk, DeFi, etc.
  Math, .../Math/     # Calculus, Linear Algebra, Probability, Statistics,
                      #   Stochastic Processes
  Tech/               # Software engineering, systems, programming languages
  Cooking/            # Recipes
  English/            # Vocabulary
  Interviewing/       # Interview prep
  Leadership/         # Management and leadership notes
3 - References/       # External references
code/                 # Marimo notebooks (interactive math/science/finance
                      #   explorations). Has its own CLAUDE.md.
animations/           # Manim scripts for pre-rendered visualizations
quartz-publisher/     # Quartz 4 build — publishes to vault.edmondo.lol

When creating a new note, place it in the matching area. If no area fits, create a subdirectory under 2 - Areas/.

Coding standards

For any code in this vault (notebooks, scripts, build tooling), defer to the global CLAUDE.md instructions — they define Python style, type hints, test naming, project structure, and other engineering standards.

The code/ directory has its own code/CLAUDE.md with notebook-specific rules (sympy-first formulas, draw-first diagrams, self-contained uv metadata).

Research-first process for technical notes

When asked to write or expand a technical note, do not write the content directly. Instead:

Generate a research prompt for a web-connected chatbot (ChatGPT, Gemini, Perplexity). The prompt must:
- Ask the chatbot to explain the topic with citations (RFCs, official docs, design docs, papers).
- Ask the chatbot to ask the user questions to confirm understanding, check partial validity of the research, or identify gaps before continuing.
- Be specific about what the note needs to cover — not a vague “explain X” but targeted questions that would catch the kind of mistakes Claude makes (mechanisms, not just outcomes; steady-state vs. filling-up behavior; amortized vs. per-operation costs).
- Keep it factual. The research prompt asks for information only. Comprehension questions, mental-model clarifications, and “questions to sit with” belong in the final note — not in the research prompt.
Wait for the user to come back with the verified research.
Then write the note based on that research, not on training data.

This process exists because Claude will confidently construct elaborate wrong explanations (diagrams, pseudocode, formulas) on top of unverified assumptions, then dig deeper into the wrong model when challenged instead of raising a white flag. The research prompt is the white flag.

Exception: If the topic is something Claude can verify against files already in the vault or code in the repo (e.g., documenting existing code, describing a tool’s config format by reading its source), skip the research prompt and work directly.

No stub notes. Never commit a placeholder note that says “TODO” or contains just a title and an empty body. Stubs are useless — they clutter the vault and give the reader nothing. Only commit notes with substantive content that the reader can actually learn from.

Writing the note is not reformatting. When the user brings back research, do not just add markdown headers and call it done. Apply the full quality standards below: problem→mechanism→tradeoffs, historical context, term definitions on first use, diagrams for flows, worked examples. The research is raw material — the note is a teaching document.

Note quality standards

The reader should be able to navigate this vault without mental strain. Every note must be self-contained enough that the reader can follow the argument without opening ten other tabs — but it should not over-explain things the reader obviously already knows.

The jargon rule: keep it, but introduce it

Use industry terminology — the reader wants to learn the words professionals use so they can have real conversations. But every non-obvious term must be briefly explained on first use (one parenthetical or one sentence) and linked to a deeper note if one exists.

What counts as “non-obvious” depends on the note’s audience (see Knowledge Calibration under Finance). The test: if a smart person outside the field would pause and think “wait, what’s that?”, it needs a gloss. Examples:

Yes, explain: “marginal price” (= the current quoted price), “adverse selection” (= being on the wrong side of informed trades), “sech” (= hyperbolic secant, a bell-shaped function), “bps” (= basis points, 1 bp = 0.01%), “arbitrageur” (= bot/trader exploiting price differences), “convexity” (= curves upward, each additional unit costs more).
No, don’t explain: “probability”, “derivative” (calculus sense), “interest rate”, “stock”, “bond”, “database”, “API”, “function”, “variable”. These are common knowledge for the target reader.

Other quality rules

Define acronyms and names on first use. If a section is called “TAP and TUN”, explain what TAP and TUN stand for before anything else.
Explain the “why” before the “what”. If something is described as “instead of X”, make sure X was explained first.
Cover the mechanism, not just the outcome. Don’t just say a tool “uses” a feature — explain how it uses it (the syscalls, the data flow, the lifecycle).
Worked examples for abstract concepts. Step-by-step packet flows, command outputs, or C-level snippets where they make the concept concrete.
Prefer diagrams over prose for flows and processes. A merge process, a request lifecycle, a data pipeline, a step-by-step evaluation trace — these are better communicated with a diagram than with paragraphs of text. If you find yourself writing “first X happens, then Y reads from Z, which sends to W,” stop and draw it instead. This includes multi-step sequences shown as indented text or pseudo-traces in code blocks — those are ASCII diagrams in disguise. Prose should set up context and explain tradeoffs; diagrams should carry the structural and sequential information.
No ASCII art diagrams. Never use ASCII/Unicode box-drawing characters to represent structures, flows, or layers. Always create a proper SVG diagram via a script in docs/diagrams/. ASCII art is ugly, hard to maintain, and inconsistent with the vault’s visual standard.
Consistent visual style within a note. Every visual in a note must be an SVG diagram. Do not mix formats. If a note already has a diagram rendering script, add the new diagram there.
Introduce before referencing. Never use a concept, function, or term as part of an explanation before the reader has seen it defined. If Section 3 relies on mem::swap to explain Pin, mem::swap must appear in Section 1 or 2 with what it does and why it matters. If you catch yourself writing “recall that X” and X was never introduced, stop and fix the ordering. This applies equally to prose notes and notebook sections.
Show the diagram first, then explain. Place diagrams at the top of the section they belong to, before the derivation or detailed explanation. Follow each diagram with a short caption (1–2 sentences) describing what the reader is looking at — enough to orient them, not a full explanation. The detailed math and prose come after. The visual gives intuition; the text formalizes it. Never bury a diagram at the bottom of a wall of text.
No dangling wikilinks. If you write [[QEMU]] or [[Virtio]], check whether the target note exists. If it doesn’t, create it.
No filler transitions or throat-clearing. Never announce what you’re about to say — just say it. The reader will see that the next paragraph explains why; you don’t need to promise it. Banned patterns (non-exhaustive):
- Announcements: “Here’s why”, “Here’s what’s actually being claimed”, “Let’s explore”, “Let’s dive in”, “Now ask:”, “It’s worth noting that”
- Inflated labels: “This is the conceptual heart”, “This is the computational workhorse”, “Two headline insights”, “the complete reconstruction”
- Hedging filler: “In this sense”, “exactly” (when the math already says =), “Obviously” (before rhetorical questions)
- Rhetorical walk-throughs: “Now ask: what is X?” → “We want X.”
- Redundant intensifiers: “actually invert each other rigorously” when “invert each other” suffices in context where rigor was already established

Intuition preambles for math-heavy notes

Notes that contain derivations or formulas must open with a plain-English intuition section before any math. This section should:

Explain the concept with a concrete example (real numbers, real tokens, real dollars).
State the key insights as bullet points a non-specialist can follow.
Include a > [!info] Prerequisites callout linking to the notes the reader should have seen first.

The math then follows for readers who want the derivation. The intuition section ensures that readers who aren’t ready for the math still walk away understanding the concept.

Notation callouts for Greek letters and symbols

If a note uses Greek letters ( $α$ , $γ$ , $Δ$ , $λ$ , $σ$ , etc.) or mathematical notation that isn’t universally familiar, add a > [!info] Notation callout early in the note listing each symbol and what it represents in this context. Don’t assume the reader remembers which Greek letter means what.

Self-consistency — no contradictions within a note

After writing or editing a note, re-read every factual claim and verify that no other sentence in the same note contradicts it. This is the single most common failure mode. Examples of contradictions that were NOT caught:

Intro says “merge files into larger ones” → body says “all files are the same size.”
One paragraph says levels “hold the same data” → next says “different subsets of keys.”
Describes rewriting files “even though nothing changed” → the merge-sort description three lines later shows them changing.

Each sentence sounded plausible in isolation; together they are nonsensical. If two statements cannot both be true, one of them is wrong. Fix it before committing. Do not require the user to find these.

Mechanism before formula

Never present a formula, cost model, or complexity analysis before explaining the mechanism it describes. The ordering is always:

What problem does this solve?
How does the mechanism actually work? (pseudocode, step-by-step, diagram)
Now derive or present the formula from the mechanism.
Tradeoffs and parameter choices.

A formula without mechanism is a magic number. The reader cannot evaluate whether the formula is correct, or reason about when it breaks down.

Verify your own output

Before declaring any work done:

Code: run it. If a notebook, open it and verify every cell renders.
Links: check they resolve (rendered notebooks, wikilinks, section anchors).
Diagrams: look at them. Ask “what would a naive reader conclude from this image alone?” If the visual message differs from the intended one, redraw.
Multi-stage systems: if the note describes a pipeline, layered architecture, or any system with distinct stages, verify it explains how things move between stages. If you describe the stages but not the transitions, the reader has no mental model of flow.

Do not skip this because the code “looks right.” Silent failures (cells that error without visible output, functions that return empty lists for certain inputs, dropdowns with wrong parameter names) are only caught by running the code.

Every section must belong to the note’s concept

Before adding a section, ask: “does this belong to the concept this note is about?” If the content is tangential, it goes in a different note or nowhere. Example: a section on “histogram bucket explosion” does not belong in a note about label cardinality — histogram buckets are metric values, not labels. Including irrelevant content erodes the reader’s trust in the rest of the note.

Pre-completion checklist — mandatory before every commit

Before committing any note change, read the full note top-to-bottom through the eyes of the target reader (see Knowledge Calibration). For every non-obvious term that causes a moment of “wait, what’s that?”, add a brief inline explanation. This is non-negotiable. Do not require the user to point out missing definitions.

Specifically check every:

Acronym — expanded on first use, no exceptions. This includes common-sounding ones: ANN, kNN, IVF, BDR, DDL, DML, CTEs, OPA, RBAC, ABAC, ACL, CNCF, GTID, etc.
Algorithm or data structure name — briefly explained (e.g. “beam search”, “skip list”, “Voronoi cell”, “Datalog”).
Scientific or mathematical adjective — defined inline (e.g. “anisotropic — direction-dependent”, “isotropic — equal in all directions”, “convex — curves upward”).
Industry jargon — explained in a parenthetical on first use (e.g. “marginal price (the current quoted price)”, “adverse selection (being on the wrong side of informed trades)”). Keep the jargon — the reader wants to learn the professional vocabulary — but never assume they already know it.
Greek letters and notation — add a notation callout if the note uses $α$ , $γ$ , $Δ$ , $λ$ , $σ$ , etc. One line per symbol: what it is, what it means here.
Proper noun used as a technical concept — explained the first time (e.g. “Lucene”, “Tantivy”, “Zelkova”, “s2n-tls”, “ProxySQL”).
Tool, library, or project name — if you mention a tool in comparison or as something being replaced (e.g. “replaces tox and nox”, “like pnpm”), explain what it is and what it does before the comparison. The reader may not know it. If the tool has its own note, link to it; if not, explain inline (one sentence minimum: what it is, what it does, when it was created).
Forward reference — if a term is used before the section that defines it, add a one-line inline definition or a pointer (“see X below”).
Currency dollar signs — Quartz and Obsidian interpret bare $ as LaTeX math delimiters. Any $ used as a currency symbol (e.g., $78B, $2.7T, $100.03) must be escaped as \$. Unescaped pairs of currency $ signs cause intervening text to render as italic math gibberish. After writing any note with dollar amounts, grep for [^\\]\$[0-9] and fix every match.
Wikilink — resolves to an existing note. If the target doesn’t exist, create a stub.
Self-contradiction — re-read every claim and verify no other sentence in the note says the opposite. See “Self-consistency” section above.
Mechanism before formula — if a formula appears, verify the mechanism it models was explained first. See “Mechanism before formula” section above.
Complete lifecycle — if the note describes a multi-stage system (pipeline, tiered storage, protocol handshake, etc.), verify it explains how things move between stages. Entry → processing → exit → where does the output go? If any transition is missing, the reader has no mental model of the flow.

Additionally, verify internal consistency:

Claims must match their evidence. If a paragraph makes a claim (“X is harsher than Y”) and a table or formula nearby shows numbers, check that the numbers actually support the claim. Read the table. Do the arithmetic. A prose claim that contradicts its own table is worse than no claim at all — it actively misleads the reader.
Comparisons must be unambiguous. If you say “A is more X than B”, the reader must be able to verify this from the data in the note. If the relationship is nuanced (e.g., “A is convex but still less than B at every point”), say exactly that — don’t flatten it into a misleading superlative.
Qualitative summaries must survive a spot check. Pick two rows from any table and verify the surrounding prose correctly describes the pattern. If the summary says “grows faster” but the numbers show it grows slower, fix the summary.
Compute derivatives — don’t guess their signs. When a note describes a function as convex, concave, increasing, or decreasing, actually differentiate the formula and verify the sign. Do not infer curvature from the name of the concept or from intuition about what “should” be true. Wrong signs on derivatives produce notes that contradict their own charts and tables.
Distinguish different functions in the same system. A system may have multiple related functions (e.g., a price curve and an impact function) with different curvatures. Name each function explicitly, state its curvature separately, and never transfer a property from one to the other. If the reader could confuse them, add a comparison table.
Lead with geometry, support with calculus. When explaining why a curve bends a certain way, describe the shape first (“the curve gets steeper near zero and flattens out as x grows”). Then optionally connect it to derivatives for readers who want the formalism. Never lead with the second derivative and expect the reader to reconstruct the shape from the sign.
Track every variable through a multi-step process. When a formula involves related but distinct quantities (e.g., Δx vs Δx_eff, gross vs net, pre-fee vs post-fee), the note must make crystal clear which quantity is used at each step. Use numbered steps (“Step 1 — the trader sends Δx”, “Step 2 — the pool computes Δx_eff”) and never switch between the two without saying which one and why. A concrete numerical example (e.g., “1,000 X at 0.3% fee → 3 X fee, 997 X enters the formula”) eliminates ambiguity that symbols alone leave.
Context-dependent equivalences are not general equivalences. Two concepts may coincide in a specific context but differ in general. When this happens, explain why they coincide here and state clearly that this is not always the case. For example: “On a bonding curve, buying mints new tokens — because this is a primary market and no tokens exist beforehand. On a secondary market (an AMM), buying just transfers existing tokens.” Never write “buying = minting” as if they are synonyms. The reader must understand the scope of the equivalence, not carry away a false general rule.
Surface hidden prerequisites. If a note’s explanation only makes sense once you understand a concept that is never introduced in the vault, that concept is a hidden prerequisite. Don’t paper over it with a parenthetical — create a dedicated note that teaches the prerequisite from scratch, add a > [!info] Prerequisites callout linking to it, and insert it into the reading order. Example: MEV notes assumed the reader understood mempools and block producer ordering power, but no note explained the transaction lifecycle. The fix was a new foundational note, not a longer glossary entry.

Do not delegate this check to the user. When in doubt about whether a term is obvious, err on the side of a brief parenthetical — it costs a few words and saves a reader’s flow.

Deduplication

Each concept lives in exactly one note. If content already exists in note A, note B must link to A rather than repeat it.
Before adding a section to a note, grep for the same content in other notes. If it already exists, delete the duplicate and add a > See [[NoteA]] for … callout instead.
Search → Read → Enrich → Link. Before writing an inline explanation for any concept, search the vault for an existing note. If one exists, read the relevant section. If coverage is insufficient, enrich the existing note — add the missing explanation there, in its canonical home. Then link to it with a section anchor and one sentence of context. Never duplicate knowledge because the target note is shallow — fix the target note instead.

Linking

Use Obsidian wikilinks: [[Note Name]] or [[Note Name|display text]].
Wikilink at first mention in body text, not just in the See Also footer. The first time a concept appears in the prose, link it: “uses the GGUF format”. The See Also section is for discovery of related topics the reader might not think to look for.
Add See also sections at the bottom of every note that has meaningful neighbours.
When creating a new note that is referenced from an existing note, verify the wikilink in the existing note resolves (correct capitalisation, no extra spaces).
Link companion notebooks with wikilinks: [[code/topic-name/notebook]] (not raw file paths). The notebooks are rendered automatically and should be clickable from the note.

Reading order for learning sequences

When notes form a learning sequence (e.g., the DeFi path, the market microstructure path), the first note in the sequence must include a > [!tip] Recommended reading order callout near the top listing the full path with wikilinks. Each note in the sequence should only use concepts introduced in earlier notes.

If a note references a concept from a note the reader hasn’t reached yet in the recommended order, either:

Add a brief inline explanation (one sentence) so the reader can keep going without detour, or
Restructure the reading order so the dependency comes first.

Never assume the reader has read all notes — assume they followed the recommended path and nothing else.

Tech and tooling notes

Notes about tools, frameworks, and ecosystems (under 2 - Areas/Tech/) have additional requirements beyond the general quality standards:

Show, don’t list. Never describe a tool as “fast” or “extensible” without concrete evidence. Show the actual command, the actual config, the actual output. A bullet list of features is not a note — it’s marketing copy.
No marketing copy. If a bullet point reads like a press release (“Model modularity: each model is self-contained, simplifying integration”), it has no place in the vault. Either explain the mechanism in depth or remove it. If you can’t explain WHY something matters in 2-3 sentences, you don’t understand it well enough to include it.
No version changelogs. A knowledge note is not a release notes page. “v0.5 added X, v0.6 added Y” is noise. Describe the current state of the system. Mention history only where it explains WHY something works the way it does.
Describe current state, not evolution stages. Don’t frame sections as “Phase 1… Phase 2…” when both things coexist. The reader thinks Phase 1 is deprecated. Instead: “Ollama is built on llama.cpp; it also ships a custom backend for architectures llama.cpp doesn’t support.” Use history as context, not as structure.
No “table stakes” sections. If something is basic expected functionality (“handles inference contexts”, “manages memory”), don’t give it a section header. That’s like documenting that a web server accepts HTTP requests. Only document what’s distinctive or non-obvious.
Practical examples for every tool. How to start a project, how to add a dependency, how to build, how to publish. Actual pyproject.toml snippets, actual CLI commands, actual directory structures.
Explain the mechanism. If a tool “resolves dependencies faster”, explain why (Rust resolver, SAT solver, caching strategy). If a tool “doesn’t have lockfiles”, explain what it does instead and the consequences.
Comparison notes must have a “when to use” section. Not just feature matrices — concrete guidance: “if you are building X, use Y because Z.”
Decision matrices for selection. When recommending models, tools, or configurations, include: a budget/resource table with concrete numbers, a task-to-recommendation matrix, overhead/switching costs, and performance expectations. The reader needs to make decisions, not just learn facts.
Setup instructions belong in the tool’s note, not the platform’s. A note about Ollama should explain integration patterns (API compatibility, keep_alive semantics, localhost detection). The step-by- step setup guide for FluidVoice-with-Ollama goes in the FluidVoice note. Instruction-manual content is ephemeral and belongs with the tool it configures.
Create dedicated deep-dive notes. When a concept deserves depth (quantization, tokenization, embeddings), create a separate note that goes implementation-level deep. The parent note links to it with one sentence of context — enough for the reader to know whether to follow the link. Never cover a deep topic shallowly inline.
Historical context matters. Why does this tool exist? What problem was the author frustrated with? What did it replace? What influenced what?

Anticipate reader questions

A note is not just a reference — it is a learning tool. Before finishing a note, ask: “What would a reader who just learned this concept immediately want to know next?”

Fundamentals before internals. Answer “what is this?”, “what does it produce?”, and “how do I use it?” before explaining how it works internally. A reader who doesn’t yet know what a derivation is cannot benefit from learning how thunks are forced. Structure every note so the obvious beginner questions are answered in the first sections, and the deep mechanics come after. If you find yourself using a term the reader hasn’t seen defined yet in this note, you’ve ordered things wrong.

Examples of questions that must be answered proactively:

If a note describes a protocol that is “compatible with X”, explain: is X built on this? Is this a reimplementation? Why does the compatible version exist?
If a note describes two similar components (e.g., two types of management daemons), explain: why do both exist? What is the boundary between them? What happens if each one fails?
If a note describes a technology the reader might buy or use, include: how do I check if my hardware supports it? How do I verify which version I have? What are the practical decision factors (cost, compatibility, alternatives)?

Structure patterns

Problem → approach → mechanism → tradeoffs. For any algorithm or system:

What problem does it solve? (With scale / latency numbers where relevant.)
What is the core insight or approach?
How does it actually work? (The algorithm, data structure, or protocol steps.)
What are the parameters and their tradeoffs?

Tables for comparisons. Side-by-side tables beat prose when comparing multiple algorithms or options. Include a “Notes” column for caveats.

Callouts for warnings and tips. Use Obsidian callout syntax:

> [!warning] Title
> 
> Content

> [!tip] Title
> 
> Content

> [!info] Title
> 
> Content

See also section. Every note with meaningful neighbours gets a ## See also section at the bottom with wikilinks.

When to create a notebook. Some notes benefit from a companion Marimo notebook — an interactive app that lets the reader explore the concept with live controls. Worth building for topics where tuning parameters and seeing the effect matters: ANN algorithms, data structures with emergent behaviour, numerical methods, financial models. Don’t create one for purely definitional notes. Notebooks live in code/<topic>/notebook.py and have their own conventions in code/CLAUDE.md.

Diagrams

Diagram scripts live in docs/diagrams/ and render SVGs into the note’s diagrams/ subdirectory (e.g., 2 - Areas/Tech/Security/diagrams/). Notes embed them with ![[diagram-name.svg]].

Color palette. Use material-design 300/400 weight fills — soft enough to read comfortably in both light and dark Obsidian themes. Avoid saturated 700-900 fills (#C62828, #1a5ad7, #2E7D32) for large areas; they strain the eyes. Preferred palette:

Role	Color	Weight
Red accent	`#E57373`	300
Blue accent	`#5C6BC0`	400
Green accent	`#66BB6A` / `#81C784`	400 / 300
Purple accent	`#BA68C8`	300
Light fills	`#E3F2FD`, `#E8F5E9`, `#F5F5F5`	50-100

Font sizing. Node labels 12px minimum (10px is too small when embedded in notes). Titles 16px. Edge labels 9-10px.

Spacing. For graphviz TB layouts, ranksep >= 0.8 to keep edge labels from crowding arrows. For svgwrite, PADDING_X >= 100 to prevent actor boxes from clipping at viewport edges.

Graphviz pitfalls with diagram-testkit:

Do NOT use style="filled,rounded" on box nodes. Graphviz emits rounded boxes as <path> elements (not <rect>), and the linter’s “path crosses text” check flags the node’s own background path as overlapping its label. Use style="filled" instead.
Avoid edge labels when edges are short or parallel — they trigger “path crosses text” failures. Prefer conveying information in node labels or captions.

Separate protocols from products

When a technology involves both an open protocol and a commercial service built on it, structure the note to make the boundary clear:

Clearly label which features are part of the protocol (open, available in any implementation) vs which are specific to the commercial product (proprietary, may have pricing, may not be available in alternatives).
If the protocol deserves its own note (e.g., WireGuard vs Tailscale, Thunderbolt vs eGPU enclosures), create a separate note for the protocol and link to it.

Finance and economics content

The 2 - Areas/Finance/ section was merged from a standalone learning-finance project. These notes have specific conventions:

Teaching approach

Blend three personas depending on context:

Patient Professor — when introducing a topic from scratch, build up carefully. Don’t skip steps.
Sharp Colleague — when in familiar territory (instruments, accounting, markets), be direct and assume intelligence.
Socratic Tutor — regularly ask questions back. Test understanding. Challenge assumptions.

Content style

Use math generously. Formulas and derivations are a first language. Build intuition alongside the math, not instead of it.
Use code (Python). Monte Carlo simulations, pricing algorithms, and numerical examples illuminate concepts. Code should explain the financial meaning, not just the programming mechanics.
Use engineering analogies where they genuinely help: distributed systems → market microstructure, optimization under constraints → portfolio theory, state machines → derivatives lifecycle, streaming vs. batch → real-time vs. end-of-day risk.
Rich historical context. Who developed the idea, when, what problem they were solving, how it evolved or was challenged.
Flag debates and controversies. Present the mainstream view, then flag significant disagreement (EMH, CAPM failures, Black-Scholes assumptions in practice). Let the reader form their own view.
Connect to professional experience: Gottex (yield curve optimization, brokerage), Goldman (market making, exchange connectivity), Credimi (credit scoring, underwriting, SMB lending), Capital One (fraud detection, credit card risk).

Knowledge calibration

Assume the reader:

Knows well: accounting, financial statements, futures, swaps, options mechanics, Greeks (what they measure), DCF, corporate finance basics, practical credit scoring/underwriting pipelines, numerical optimization.
Knows the shape but not the depth: binomial pricing, Black-Scholes (what not how), implied volatility (intuition not theory), portfolio theory (Markowitz vaguely), fixed income (partial formal exposure).
Wants to fill: market microstructure, derivatives pricing theory, structured products, debt capital markets depth, fixed income theory, credit risk theory, macro/monetary economics, stochastic calculus.
Has never been formally taught statistics or probability — flag when these prerequisites arise and teach briefly or link to the Math/Probability notes.

”Questions to sit with” sections

Every substantive Finance note ends with a Questions to sit with section — 2–4 open-ended questions that test whether the reader truly understood the material. These are not quiz questions with right answers; they are prompts for deeper thinking that connect the note’s concepts to adjacent ideas, surface hidden assumptions, or ask the reader to apply the framework in a novel context.

Guidelines:

Place them after the main content, before ## See also.
Frame each question so it requires the reader to synthesize, not just recall. “What is a straddle?” is bad. “An LP’s ‘strike’ drifts as price moves — does the short-straddle analogy still hold?” is good.
Cross-reference other notes where the question bridges two topics.
When the reader returns with answers, update the note: replace the questions with the answered versions (keeping the questions as headers and adding the discussion below each).

Reference textbooks

Hull (derivatives), Fabozzi (fixed income), Shreve (stochastic calculus), Cochrane (asset pricing), Harris (market microstructure), Tuckman (fixed income), Lopez de Prado (financial ML).

Math content (Calculus, Probability, Statistics, Stochastic Processes)

The Math/Calculus/, Math/Probability/, Math/Statistics/, and Math/Stochastic Processes/ directories contain rigorous mathematical foundations that serve multiple downstream areas (finance, physics, ML). These notes:

Derive, don’t just state. Show where formulas come from.
Use measure-theoretic language where appropriate ( $σ$ -algebras, measurable functions, $(Ω, F, P)$ triples).
Include worked numerical examples alongside the theory.
Maintain a dependency graph — each article states its prerequisites and what it unlocks.
Keep source_conversations frontmatter for provenance tracking.

Theorem structure in math notes

Every theorem, proposition, or lemma must have its logical structure visible at a glance. Use this format:

> **Hypothesis:** [what we assume]
>
> **Thesis:** [what we prove]

Then a ### Proof section with the argument. End proofs with $□$ .

Never bury the hypothesis inside prose. Never let the reader wonder “what are we assuming?” or “what are we trying to show?” If a proof step uses the hypothesis, say so explicitly (“by hypothesis, $F^{'} = f$ , so…”). The reader must be able to trace every step back to either a hypothesis, a definition, or a previously proven result.

Prose explanation (intuition, physical analogies, “why this is non-trivial”) goes between the theorem statement and the proof — never interleaved with the proof steps.

Sourcing content from conversations

When the user asks a question during note creation (e.g., “how does MVT relate to FTC?”, “why is this not just a definition?”), include the answer in the note — but rephrase it as standalone content. The note must read as if it were written from scratch, not as a response to a question. Never include:

Anecdotal framing: “The professor remarked…”, “As discussed…”, “You asked about…”
Conversational attribution: “The reason I bring this up is…”
Contingent phrasing: “Since you mentioned X…” or “This came up because…”

Instead, ask yourself: why did the user ask this question? What confusion or gap does it reveal? Write the section to address that gap directly. If the user asked “how is MVT weaker than FTC?”, the note should have a section comparing MVT and FTC on its own merits — not a section that exists “because the professor said so.”

Proof step format

Each proof step is one atomic action followed by one formula. No prose paragraphs between formulas. No multiple operations conflated in a single step. Format:

**Step N.** [One sentence: what you do and why.]

$$[formula]$$

Rules:

One action per step. “Substitute hypothesis” is one step. “Divide by $h$ ” is one step. Never “substitute and simplify and rearrange.”
The sentence says what operation you perform (e.g., “Divide by $h$ ”, “Substitute the hypothesis $F^{'} = f$ ”, “Take $n \to \infty$ ”). If the justification isn’t obvious, add it after a period or dash.
The formula stands alone on its own display line ($$...$$).
No run-on prose between steps. The visual rhythm is: bold label → short sentence → formula → blank line → next step.

No editorial commentary around proofs

The proof speaks for itself. Never add prose before or after a proof that tells the reader how to feel about it, how easy it is, or what it doesn’t use. Banned patterns:

Difficulty assessments: “This is almost immediate”, “The proof is straightforward”, “This is trivial but instructive”, “The hard part is Step 3”
Negative announcements: “No MVT needed”, “We don’t use X here”, “Unlike the previous proof, this one…” — the reader can see what the proof uses by reading it
Rhetorical questions as headers: “Is this circular?”, “Why does this work?”, “What goes wrong if…?” — state the content directly. Use “Logical dependency” not “Is this circular?”
Meta-commentary: “This follows purely from the definition”, “The key insight is…” (after the proof already showed it), “Note that we only used…”
Apologetic parentheticals: “(same technique as the X proof)”, “(this is just Y in disguise)” — either explain the connection properly in its own sentence or don’t mention it

If something about a proof is genuinely surprising or non-obvious (e.g., ” $G^{'} (x) = f (x)$ looks tautological but involves two different limiting processes”), that explanation goes before the proof as motivation — not after it as commentary.

Diagram–text balance in math notes

Math notes — especially geometry and calculus — must balance visual and symbolic content. A note that is all derivation with no diagrams forces the reader to build spatial intuition from symbols alone, which is unnecessarily hard. Conversely, a note that is all pictures with no rigor teaches nothing lasting.

Rules of thumb:

Every geometric concept gets a diagram. If a section discusses tangent vectors, level curves, constraint surfaces, or any spatial relationship, it needs a visual. Text-only geometry is useless.
Diagrams come first in each section (see the general diagram rule above). The reader sees the picture, reads a short caption, then works through the derivation with the image in mind.
Alternate between visual and symbolic. A long stretch of pure LaTeX (more than ~20 lines without a diagram, table, or concrete example) is a signal that the note needs a visual break. Insert a worked example, a diagram, or a summary table.
Concrete before abstract. When introducing a method (e.g. Lagrange multipliers), show a specific example with numbers and a picture before stating the general theorem. The reader should see why the method works on a case they can visualize before encountering the $n$ -dimensional generalization.

Commit discipline

One concern per commit. Don’t mix content changes with link fixes or new notes in the same commit.
Commit message format: docs: <imperative summary> (e.g. docs: expand TAP/TUN section with packet flow examples).
After committing, always push to gitlab immediately.

Edmondo's Vault

Explorer

CLAUDE