Skip to content

Writing RAMAL-EBX in Obsidian

Open [[docs/gen_ai/README|the generated documentation index]] when you need the AI-maintained map of the implemented system.

Ownership

  • docs/human/ contains only notes written by the project owner. These notes are the primary source for intent, priorities, scientific judgment, and paper direction.
  • docs/gen_ai/software/ contains AI-maintained maps and guides for the reusable application.
  • docs/gen_ai/research/<paper>/ contains each paper's AI-maintained research plan, literature review, and annotated bibliography.
  • references/ contains external literature snapshots. Each paper's annotated bibliography records their relevance and limitations; cataloging a source does not make its claims accepted project decisions.
  • Executable code remains authoritative for what the software currently does. Human notes remain authoritative for what it should become.

AI must not edit, create, rename, or delete anything under docs/human/ unless the project owner explicitly requests that exact file operation. Normally, AI reads those notes and changes code or docs/gen_ai/ instead.

Start with four human notes

Create these yourself under docs/human/. They can begin as a few rough sentences.

Project Direction.md

Write in first person. Useful prompts:

  • Why am I building RAMAL-EBX?
  • Who should it help, and what should they be able to do through the GUI?
  • What scientific and product qualities are non-negotiable?
  • What feels wrong or alien in the current codebase?
  • What am I deliberately not building?

Paper 1.md

Keep your scientific thinking separate from implementation status:

  • research question
  • intended claim or contribution
  • why the question matters
  • physical scope and exclusions
  • proposed method
  • evidence required before making the claim
  • figures and tables you expect the paper to need
  • uncertainties, objections, and competing interpretations
  • decisions you have made versus questions still open

Do not force this into polished academic prose. It is a thinking record first.

Plans.md

Use three headings: Now, Next, and Later. For each active item, write the outcome you want and how you will recognize that it is done. Keep implementation details out unless they constrain the outcome.

Inbox.md

Capture fragments immediately: observations, doubts, paper ideas, UI complaints, experiment ideas, and questions. Move or link an item only when it becomes important. An untidy inbox is better than losing the thought.

Make meaning explicit

Use these markers when ambiguity would matter:

  • Decision: committed direction; AI may implement it.
  • Idea: candidate, not permission to implement.
  • Question: unresolved; AI should investigate or ask before choosing a consequential answer.
  • Concern: something that may be wrong, risky, or inconsistent.
  • Observation: what you saw; treat it as ground truth about your experience.

Plain prose is still fine. The markers exist to prevent an AI from promoting speculation into project policy.

How notes drive work

human observation or idea
        -> human decision or explicit request
        -> code change
        -> verification through the real workflow
        -> gen_ai documentation updated to describe reality

If human intent and current code disagree, AI should identify the mismatch and adapt the code when requested. It must not rewrite the human note to make the disagreement disappear. If generated documentation disagrees with either, regenerate or delete the generated documentation.

A useful AI request

Read the relevant notes under docs/human/ first. Treat decisions there as project direction and distinguish them from ideas and questions. Inspect the current code, explain any mismatch, then update the code and docs/gen_ai/ documentation. Do not modify docs/human/.

For paper work, add:

Separate my proposed claims from implemented methods and accepted evidence. Do not describe planned or historical results as current evidence.

Obsidian habits that are enough

  • Link related notes with [[Note Name]] when the relationship is useful.
  • Use backlinks to see where an idea influences plans, software, or the paper.
  • Prefer one living note per subject over a deep folder hierarchy.
  • Write dates beside decisions whose context may change.
  • Keep contradictions visible until you resolve them; do not polish them away.

No plugin or elaborate taxonomy is required. The ownership boundary and regular writing matter more than vault mechanics.