Obsidian Notes Creator

Make notes accurate, easy for the intended reader to understand, and useful for solving unfamiliar problems. Match depth to the learner and the requested scope; decoration and length are not evidence of quality. Correct but hard-to-read notes are not finished.

1. Inspect and choose the mode

• Create: identify the source, audience, prerequisites, and learning objectives before choosing a structure.
• Improve: read existing notes, neighbouring notes, assets, and relevant vault instructions. Repair and deepen those files in place. Preserve filenames, folders, links, original dates, and useful author wording. Do not create a parallel study guide, rename files, or impose a new folder tree unless requested or necessary to the task.
• Audit: report specific gaps with file references; do not silently rewrite an audit-only request.

Know the reader. Before writing, state in one or two sentences who the reader is and what they already know (for example, "comfortable with Python and high-school algebra, new to this notation"). Build explanations on that knowledge. Ask the user when it is unclear and it would change the writing.

For a folder-wide task, inventory every Markdown file first. Track each as unreviewed, reviewed unchanged, improved, or unresolved, with a short reason. A small selection of polished notes is a targeted pass, not a completed folder review. Keep this working record outside the notes unless requested.

Defaults: answers and solutions are directly visible; SVG figures have a white background. Explicit user preferences override these defaults.

2. Understand before expanding

Identify missing reasoning, prerequisites, assumptions, definitions, and misleading claims. Distinguish source statements from derived examples and uncertain material. Keep source citations near the claims they support; never invent page numbers, measurements, or experimental results.

Prioritise correctness, complete worked reasoning, and useful connections. Add a visual, analogy, table, or exercise only when it teaches something the existing explanation does not.

• Single note: adaptable content modules.
• Multi-file notes: ownership, granularity, and preservation.
• Index notes: update existing navigation when needed.
• Scenario and case notes: fixed shapes for system-design scenarios and real-event case studies.

3. Explain and demonstrate

For unfamiliar material, connect motivation and intuition to the formal statement. Reference notes may lead with a definition; worked problems may lead with the question. No mandatory analogy or diagram quota.

Write plainly: one idea per sentence, terms defined on first use, an example right after each claim, concrete cases before the general rule, and fine-print caveats moved to a later section rather than interrupting the main explanation.

• Teaching style: reader-first writing, notation decoding, bridges from familiar ideas, common mistakes, consistent note shape, layering, practice types, clean page layout, and a final beginner read-through.

• Intuition and mathematics: symbols, assumptions, derivations, and limits.

• Analogies: explicit mapping and where it breaks.

• Examples: complete solutions, independent checks, and diagnostic questions.

• Comparisons: method choice, guarantees, and fair evidence.

4. Use the appropriate representation

Choose prose, a table, ASCII, Mermaid, or SVG according to what the reader needs to see. Keep equations in rendered LaTeX. Make visuals consistent with the surrounding worked example.

• Diagrams and SVG
• Callouts and visible answers
• Frontmatter
• Wikilinks and embeds

5. Verify and report honestly

Run scripts/check_notes.py <folder> first: it checks frontmatter, links and embeds, folded answers, long paragraphs, and renders Mermaid when mmdc is installed. Then use the verification workflow and quality checklist. Verify calculations separately from rendering. Tag every number by its source and paste real code output. Inspect generated figures at their intended embed size. Check changed links and assets.

Report coverage, substantive improvements, checks actually run, and unresolved issues. Distinguish reviewed, executed, and rendered. Never claim exhaustive validation from samples, syntax checks, or file counts alone.