Lab Wiki Authoring
The lab wiki lives at https://coleoguy.github.io/knowledge/ in the Jekyll
repo at ~/Desktop/GitHub/coleoguy.github.io/.
Two Entry Points — Choose the Right One
1. Ingesting a new paper end-to-end
Use ingest_paper_to_wiki. The pipeline encodes all rules in this document
automatically. You do not need to read this skill for that path.
2. Any ad-hoc wiki operation — hand-editing a topic page, fixing a
cross-link, creating a topic from scratch, renaming a paper, splicing in a new
finding, or any change not driven by ingest_paper_to_wiki:
Before writing a single line, call read_wiki_handoff().
That tool returns the full WIKI_HANDOFF.md spec (~260 lines). The rules
in this SKILL.md summarize it; the handoff is authoritative. Writing to
/knowledge/ without reading the handoff is a reliable way to break the
live landing page.
Directory Structure
knowledge/
├── index.md ← SINGLE consolidated landing page — do NOT touch
├── papers/
│ └── 10_1534_genetics_117_300382.md ← DOI-slug filenames
├── topics/
│ └── sex_chromosome_evolution.md
└── repos/
└── evobiR.md
Critical: knowledge/papers/index.md, knowledge/topics/index.md, and
knowledge/repos/index.md MUST NOT EXIST. They were deleted intentionally.
The landing page uses Jekyll Liquid to pull all three sections dynamically.
If you create sub-index files, duplicate navigation appears and the site breaks.
Slug Rules
Paper slugs (DOI-derived)
DOI: 10.1534/genetics.117.300382
File: knowledge/papers/10_1534_genetics_117_300382.md
Replace every / and . with _. For papers without DOIs, use a lowercase
underscore-separated descriptive slug. Do NOT create new pages with year-letter
slugs (e.g. 2014b.md) — those are legacy files being migrated by the Canon
rename agent. Do NOT manually rename existing legacy files.
Topic slugs
Lowercase, underscores, descriptive. Example: karyotype_evolution,
fragile_y_hypothesis, sex_chromosome_evolution.
Required Frontmatter — Paper Pages
Every field must be present. Missing fields cause silent rendering failures.
---
layout: default
title: "Full article title exactly as it appears in the paper"
doi: 10.1534/genetics.117.300382 # no https://doi.org/ prefix; empty string if none
fingerprint_sha256: d067836a... # SHA256 of the source PDF used for grounding
authors: "Blackmon H, Brandvain Y" # full author string from paper
journal: "Genetics" # journal name; empty string if preprint/book
year: 2017 # integer, not string
topics: [fragile_y_hypothesis, sex_chromosome_evolution, sex_linkage_mutation]
tier: canon # canon | standard | peripheral
ingested_at: 2026-04-21T14:53:07.827586+00:00
permalink: /knowledge/papers/SLUG/
---
# Full article title exactly as it appears in the paper
Required Frontmatter — Topic Pages
---
layout: default
title: "Karyotype Evolution" # human-readable, title case
topic_slug: karyotype_evolution # machine slug, matches filename
last_updated: 2026-04-21T18:27:18.651978+00:00
papers_supporting: [10.1534/genetics.117.300382]
permalink: /knowledge/topics/SLUG/
category: "Karyotype evolution" # REQUIRED — see category map below
---
Required Frontmatter — Repo Pages
---
layout: default
title: "evobiR"
repo: github.com/coleoguy/evobiR # no https:// prefix
language: R
papers_using: [10.1234/..., ...]
permalink: /knowledge/repos/SLUG/
---
The h1-Must-Match-Title Invariant
The title: field in frontmatter and the # H1 at the top of the body must
be identical. The landing page renders title: as the link text; stub titles
like "2014b", "2020 microsats", or "2016 saga" are unacceptable.
- Get the real title from CrossRef, PubMed, or the PDF header.
- If the paper has HTML entities in the title (e.g.,
<i>Drosophila</i>), write plain text in thetitle:field. - The body
# H1should be identical totitle:— no YAML quotes, no HTML.
Finding Anchors
In paper pages, findings use explicit HTML anchors:
<a id="finding-1"></a>
### Finding 1 — [One-sentence summary of the result]
> "Verbatim quote from the paper that grounds this finding." (p. X)
**Why citable:** [one sentence]
**Counter/limitation:** [one sentence]
**Topics:** [sex_chromosome_evolution](/knowledge/topics/sex_chromosome_evolution/),
[karyotype_evolution](/knowledge/topics/karyotype_evolution/)
Anchor IDs are sequential integers (finding-1, finding-2, ...) per paper.
Cross-references from topic pages use these anchors:
[Smith & Jones 2022, Finding 3](/knowledge/papers/10_1234_something/#finding-3)
Never use headings or slugified text as anchors — only the explicit
<a id="finding-N"></a> form is used.
The Category Field — Single Most Important Rule for Topic Pages
category: controls which collapsible group the topic appears in on the
landing page. A topic without category: is invisible to visitors.
Preservation Rule
When updating an existing topic page:
- Read the file first (
read_wiki_topic(slug)or read from disk) - Copy the existing
category:value into the new version — never drop it - Append new DOIs/hashes to
papers_supporting:— never replace the list - Update
last_updated:to the current UTC ISO timestamp
Complete Category Map (8 categories)
Sex chromosomes
sex_chromosome_evolution, fragile_y_hypothesis, sex_linkage_mutation,
y_naught_asymmetry, sexual_antagonism, sexually_antagonistic_selection,
meiotic_drive, haplodiploidy_evolution
Karyotype evolution
karyotype_evolution, karyotype_evolution_overview, chromosome_number_evolution,
chromosome_number_optima, centromere_type, centromere_evolution,
holocentric_chromosomes, chromosome_fusion, karyotype_database
Genome structure
genome_structure_evolution, genome_assembly, genome_dynamics,
transposable_elements, microsatellite_evolution, genetic_architecture
Insects & Coleoptera
coleoptera, coleoptera_genomics, coleoptera_karyotype, bee_genomics,
bee_phylogenomics, insect_genomics, Tribolium
Speciation & macroevolution
ring_species, speciation, phylloscopus, avian_evolution,
avian_hybridization, Galliformes, uce_phylogenetics,
diversification_rates, hybridization, postzygotic_isolation,
reproductive_isolation, domestication, domestication_genomics,
life_history_evolution, convergent_evolution
Population genetics
demographic_inference, conservation_genomics, conservation_genetics,
sequencing_methods, coalescent_simulation, isolation_by_distance,
effective_population_size, divergence_time_estimation, population_genetics
Quantitative genetics & epistasis
epistasis, line_cross_analysis, quantitative_genetics,
quantitative_genetics_methods, artificial_selection, dispersal,
selection_and_drift, trait_definition, comparative_methods,
ancestral_state_reconstruction
Bioinformatics & tools
bioinformatics_tools, model_organism_databases, cavefish_genomics,
circadian_rhythm_evolution
For new slugs not in this map, assign the closest category. If nothing fits,
use "Bioinformatics & tools" as a catch-all and flag the new slug in the
commit message. Never leave category: empty.
Non-Destructive Update Protocol (tealc:auto markers)
Topic page bodies use HTML comment markers to separate Tealc-managed content from Heath-authored notes:
<!-- tealc:auto-start -->
# Topic Title
## Current understanding
(synthesized prose — regenerated on every update)
## Supporting evidence
...
<!-- tealc:auto-end -->
## My personal notes
Heath's hand-written content — preserved across every Tealc update.
- Content inside the markers: Tealc-managed; regenerated on each update
- Content outside the markers: Tealc-never-touches; preserved always
- Legacy pages (no markers): treated as all-auto; wrapped in markers on next update (one-time migration)
When writing code that updates topic pages, use the helpers in
agent/jobs/wiki_pipeline.py:
_read_existing_topic_page()— get full body_split_body_by_markers(body)— returns(before, auto, after, had_markers)- Pass only the
autoregion to the topic writer _splice_auto_region(new_auto, existing_body)— reassemble the final body
Git Commit Convention
All wiki commits must be prefixed [tealc]:
[tealc] ingest 10.1093/g3journal/jkaf217 — achiasmatic meiosis
[tealc] update topic: sex_chromosome_evolution — add Smith 2025 findings
[tealc] fix: restore category: field on karyotype_database topic
One logical unit per commit. Do not batch unrelated paper ingestions or
unrelated topic updates into a single commit. The prefix makes wiki-related
history filterable via git log --grep='\[tealc\]'.
wiki_janitor Weekly Audit
wiki_janitor.py runs Mondays at 8am Central. It produces a briefing
summarizing:
- Stub titles (paper pages with year-letter slugs as title values)
- Missing
category:fields on topic pages - Title/H1 drift (title: field and # H1 no longer match)
- Broken slug cross-links
- Orphaned topic references (papers list a topic slug that has no topic file)
- Cross-link candidates (findings that should link to each other)
If Heath asks "what's the wiki status?", pull the latest wiki_janitor
briefing via run_scheduled_job("wiki_janitor") rather than re-auditing
manually. The briefing is the authoritative current state.
Pre-Commit Verification Checklist
Run from ~/Desktop/GitHub/coleoguy.github.io/ before any push:
# 1. No topic files missing category
grep -rL 'category:' knowledge/topics/*.md
# 2. Sub-index files must not exist
ls knowledge/papers/index.md knowledge/topics/index.md knowledge/repos/index.md 2>&1
# Expected: "No such file or directory" for all three
# 3. Title must match H1 in paper files
python3 - <<'EOF'
import re, os
errors = []
for f in sorted(os.listdir("knowledge/papers")):
if not f.endswith(".md") or f == "index.md": continue
text = open(f"knowledge/papers/{f}").read()
fm = re.search(r'^title:\s*"(.*?)"', text, re.MULTILINE)
h1 = re.search(r'^# (.+)$', text, re.MULTILINE)
if fm and h1 and fm.group(1).strip() != h1.group(1).strip():
errors.append(f"{f}: title≠h1")
for e in errors: print(e)
if not errors: print("OK — all titles match h1")
EOF
Tool Summary
| Task | Tool |
|---|---|
| Ingest a new paper end-to-end | ingest_paper_to_wiki |
| Any ad-hoc wiki edit | read_wiki_handoff() first, then edit |
| Read a topic page | read_wiki_topic(slug) |
| List all topic pages | list_wiki_topics() |
| Check wiki status / audit | latest wiki_janitor briefing |
| Fetch full handoff spec | read_wiki_handoff() |