Medical Research Wiki

CLAUDE

4 min read

CLAUDE.md — How to work in this wiki

This is a personal medical-research knowledgebase (an Obsidian vault) focused primarily on ulcerative colitis / proctitis for the vault owner (“Paul”), with secondary condition objects for sleep apnea, high cholesterol, and silent reflux. It exists to organize research and lived-experience reports toward cause / mechanism / durable-remission understanding.

It is not medical advice. Its job is to support better conversations with clinicians. Preserve safety framing on every edit (see “Safety rules” below).

Read these first (in order)

  1. SCHEMA.md — the authoritative spec: directory layout, frontmatter, controlled vocabularies, source classes, evidence levels, link conventions.
  2. index.md — the vault homepage / navigation hub.
  3. Recent log.md entries — what changed lately and why.
  4. For UC work: conditions/ulcerative-colitis/index.md (the hub) and conditions/ulcerative-colitis/central-theory.md (the evolving causal model).

Mental model of the structure

  • raw/ — immutable captured sources (papers, articles, Reddit, social, Notion exports, personal notes). Never rewrite raw content; only add missing frontmatter. Synthesis happens in wiki pages, never in raw/.
  • conditions/<name>/ — top-level condition objects. Each has an index.md hub plus subpages (personal-history, research, methods, central-theory, key-insights, top-research-insights, key-open-questions, care-plan, etc.). UC is the mature one; the others are scaffolds.
  • mechanisms/ — canonical mechanism / hypothesis / biomarker pages (cross-referenced from the condition hub). This is where durable per-branch synthesis lives.
  • journal/finds/ and journal/weekly-digests/ — the chronological inbox: each research pass is written here first, then durable findings are promoted into condition/mechanism pages. Journal entries are the narrative layer; condition/mechanism pages are the organized knowledgebase.
  • _meta/ — dashboards, inventories, plans. queries/, comparisons/, anecdotes/, symptoms/, interventions/, medications-and-supplements/, clinicians-and-sources/ are cross-condition page buckets.
  • tools/ — maintenance scripts (see below). scripts/ — vault backup.

The flow is: raw source → journal find → promoted into condition/mechanism pages → indexed in index.md and logged in log.md.

Internal links are Obsidian [[wikilinks]]. To stay unambiguous (there are several index.md files):

  • Never use ../ relative prefixes in wikilinks.
  • Unique basename → bare basename: [[central-theory]], [[distal-proctitis-onset|display]].
  • Colliding basename (e.g. any index.md) → full vault path: [[conditions/ulcerative-colitis/index|Ulcerative Colitis]].
  • Give hub pages aliases: so friendly links like [[Ulcerative Colitis]] resolve correctly.
  • After editing links, run python3 tools/fix_links.py (dry run), then --apply.

Frontmatter (required on synthesized pages)

Every non-raw/ page needs YAML frontmatter with at least title, type, evidence_level, confidence (full template and the controlled vocabularies are in SCHEMA.md). Use the controlled values only — add a new type / source_class to SCHEMA.md and tools/validate_structure.py before using it. Keep updated: current.

Label epistemics honestly:

  • evidence_level: high / moderate / low / anecdotal / speculative / mixed / unknown.
  • confidence: high / medium / low.
  • Mark contested: true and fill contradictions: when evidence conflicts — preserve both sides with dates and sources, do not overwrite.

How to add a research pass (the common task)

  1. Save raw material under the right raw/ subfolder (with raw frontmatter: source_url, source_class, ingested, sha256 where possible).
  2. Write a journal/finds/YYYY-MM-DD-short-topic.md entry: what it is, why it’s interesting, which condition/branch it touches, evidence class, and whether it should be promoted.
  3. Promote durable takeaways into the relevant mechanisms/ and condition pages (key-insights.md, top-research-insights.md, key-open-questions.md, central-theory.md). Keep detail in one canonical place and link to it; don’t restate the same digest in four pages.
  4. Update index.md if you created a synthesized page, and append an entry to log.md.
  5. Cite sources with DOIs/URLs. When you use the PubMed tool, attribute PubMed and include DOI links. Never invent citations — only cite sources actually retrieved.

Safety rules (do not drop these)

  • Keep safety_flags and clinician-question framing intact. Prefer clinical guidelines over anecdotes for anything safety-critical.
  • Never present anecdotes as proof; label them evidence_level: anecdotal unless corroborated.
  • Flag danger-zone topics explicitly (e.g. DIY enemas, hydrogen-peroxide/chlorine-dioxide protocols, unscreened/DIY FMT, unsupervised antibiotics, starting smoking). These belong on clinician-discussion lists, not as recommendations.
  • This vault does not tell Paul to start/stop medications. It prepares questions for clinicians.

Maintenance / self-check

Before and after structural edits:

python3 scripts/backup_vault.py "$(pwd)"     # back up first (per log.md convention)
python3 tools/check_links.py                 # dead / ambiguous / orphan links (raw junk is ignored)
python3 tools/validate_structure.py          # frontmatter + controlled-vocabulary check
python3 tools/fix_links.py                    # dry run: normalize link style;  add --apply to write

Both check_links.py and validate_structure.py exit non-zero on hard errors, so they can gate automation. See tools/README.md for details.

Graph View

Backlinks