Wiki Conventions

Slug rules, article shape, index files, and what editing is allowed.

Slug rules

All lowercase. ASCII only. Hyphens between words. No leading or trailing hyphen. Stable across runs -- this is what makes the wiki idempotent.

• Cohort: <study>-<wave>-<sample>-<assay>. Drop fields you do not know. Example: adni-phase1-serum-lipidomics
• Institution: Short canonical name. Drop "the", "of", department suffixes unless load-bearing. Example: usc-loni-data-coordinating-center
• Investigator: <first>-<last>-<primary-affiliation>. Primary affiliation is the home institution, not the cohort. Example: michael-weiner-ucsf
• Platform: <vendor-or-site>-<technique>. Example: illumina-epic-methylation-beadchip
• Protocol: <institution>-<sample>-<assay>
• Bundle: bundle-<short-description>-<date>

Slug regex: ^[a-z0-9]+(-[a-z0-9]+)*$

Article shape

Every entity article follows this structure:

1. YAML frontmatter -- validated by the pre-write hook. See Entity Schema.
2. Title -- # canonical_name
3. Summary -- 2-4 sentences. Plain prose. No bullet points.
4. Dimension sections -- one ## dimension_name per evidenced dimension. Each section: a paragraph ending with the implication, a verbatim source quote in a blockquote with [ref: PMC...].
5. Open questions -- bulleted list. One per gap. Used by lint.
6. Links -- bulleted list of [[slug]] references to related entities.

Dimension sections

Dimension names come from references/intelligence-dimensions.md. Do not invent names. Each section has at least one paragraph with an implication and at least one verbatim quote.

When dimension 15 (biospecimen retention) is covered, the section must list specimen types banked, estimated counts, and access route. Vague statements like "biospecimens available" fail the implication test.

The card contract

The card: block is the API between the wiki and the web app. The web app reads frontmatter only, never prose.

• primary_signal -- the single standout fact. 200 chars max.
• action -- the next step a buyer takes. 120 chars max.
• risk -- the single biggest unknown. 200 chars max.

Index files

Auto-generated by scripts/wiki_index.py. Seven files under store/wiki/index/:

• master.md -- every entity, one-line summary, grouped by type
• by-indication.md -- disease to cohort list
• by-sample-type.md -- modality to cohort list
• by-institution.md -- institution to linked entities
• by-access-route.md -- access pattern to cohort list
• provenance-coverage.md -- sortable depth table
• links.md -- every back-reference, grouped by source

Idempotent: same wiki state produces byte-identical indices. Hand-edits are overwritten on the next rebuild.

What editing is allowed

• Allowed: editing entity article body (not frontmatter) to fix typos or rephrase for clarity.
• Discouraged: editing frontmatter directly. Use compile/merge or lint-driven recompile.
• Forbidden: editing index files. They get overwritten.
• Forbidden: deleting entity files. Use a merge that consolidates the entity.

Source ID format

Every entry in provenance.sources must match one of:

• PMC\d+ -- PubMed Central article
• PMID:\d+ -- PubMed ID (when no PMC exists)
• NCT\d+ -- ClinicalTrials.gov registration
• DOI:... -- DOI (when no PMC and no PMID)
• https://... -- full URL (last resort)

Source: .claude/rules/wiki-conventions.md