This document is the contract every content and data file follows. It exists so that a page written in Milestone 7 is indistinguishable in structure and rigor from the Milestone 1 exemplar.
Pages follow this exact section order. Omit a section only if it is genuinely not applicable, and never reorder.
# <Title>
> **TL;DR** — 2–4 sentences. The bottom line plus the key numbers a reader could act on immediately.
**Quick recommendations**
- Bulleted, imperative, concrete. Give ranges and numbers, not adjectives.
- Each recommendation should be defensible from the Evidence section below.
## Practical Application
How to actually implement it. Prefer tables, ranges, and explicit decision rules over prose.
## The Evidence
Mechanisms, study findings, and points of live debate. **Every substantive claim carries an evidence
grade, and every empirical claim graded A–C carries a citation.** Grade-D claims are practice-based or
mechanistic by definition (see §4) and may stand uncited *as long as they are explicitly graded D* — the
grade itself signals "reasoned/consensus, not directly evidenced." Never present an uncited claim as if
it were established fact. State where consensus is soft.
## Key Uncertainties & Nuance
What we don't know, individual variation, and the ways this topic is commonly misread.
## Backing Data
Relative links to the `data/**` files this page is derived from. Prose numbers MUST match those files.
## References
Footnote definitions (`[^key]: ...`) or a note that they are compiled in `citations/registry.md`.A page that has no structured data behind it may write Backing Data — none explicitly, so the
absence is a decision, not an oversight.
Instructional-page variant (the 09-getting-started pillar). The Getting Started pillar teaches
absolute beginners how to operate in a gym (equipment, etiquette, safety, first sessions). This
content is coaching/practice guidance, not empirical science, so those pages use a lighter,
fit-for-purpose structure: a > **TL;DR**, a **Quick recommendations** block, topic-appropriate
## sections, a ## Common mistakes or ## Key Uncertainties & Nuance section, and a ## Related
section that cross-links to the evidence pillars in place of footnote citations. They still carry
[Grade C]/[Grade D] markers on recommendations (most of this is Grade D coaching consensus, which
§4 permits uncited) — but they do not use [^footnote] citations or a ## The Evidence/## References block. The science pillars (00–08) keep the full template above.
Claim-coverage gate (npm run check). tools/check-claim-coverage.mjs fails the build if any
content page makes a [Grade A]/[Grade B] claim but carries zero [^footnote] citations —
a graded scientific claim must show its evidence. A getting-started page that states a Grade-A/B claim
by reference (linking to the fully-cited evidence pillar, as this variant permits) must be added to
that tool's short, justified ALLOWLIST. Grade-C/D claims are exempt (they can be uncited per §4).
- Layered. The TL;DR and Quick recommendations serve a beginner or a hurried lifter. Practical Application serves someone programming their week. The Evidence serves a coach or skeptic. Write so each layer is complete on its own.
- Plain, precise, non-hyped. No "revolutionary", "secret", "hack". Numbers and ranges beat intensifiers. If an effect is small, say it is small.
- Honest about uncertainty. "We don't know" is a valid and frequent answer. Distinguish what is well-established from what is plausible-but-unproven. This honesty is the product.
- Define terms on first use within a page (e.g. RIR, MEV), even if defined elsewhere.
- A citation must be real and verified. No entry enters
citations/registry.jsonuntil a live web search/fetch has confirmed the paper exists and its true metadata (title, authors, year, journal, DOI/PMID) has been captured. If you cannot verify a source, you may not cite it — reword the claim, downgrade its grade, or remove it. - Cite the strongest available source. Prefer meta-analyses and systematic reviews over single studies; prefer trained-population studies over untrained where the distinction matters.
- In prose, attach citations as footnote markers immediately after the claim:
...roughly 10+ sets per muscle per week[^schoenfeld-2017-volume-dose-response]. - Citation keys are stable, lowercase, kebab-case:
firstauthor-year-topic(e.g.refalo-2023-failure-meta). Keys never change once referenced. - In data files, cite by the same key via the
citationsarray. tools/check-citations.mjsenforces that every used key exists and every registry entry has a resolvable DOI/PMID/URL. The build is not "green" until it passes.
Apply a grade to each recommendation or load-bearing claim, written inline as **[Grade B]** or in a
table column. Grade the strength of evidence for the claim, not the size of the effect.
| Grade | Meaning | Typical basis |
|---|---|---|
| A | Strong. Act on it confidently. | Consistent findings across multiple RCTs and/or meta-analyses, ideally including trained populations. |
| B | Moderate. Reasonable default, may shift. | Several studies with some inconsistency, limited populations, or effect-size uncertainty. |
| C | Limited. Provisional. | Few studies, mixed results, or mostly untrained/short-duration evidence. |
| D | Mechanistic / practice-based. | Reasoned from physiology or coaching consensus; little or no direct hypertrophy RCT support. |
Model-based numbers are estimates. Volume landmarks (MV/MEV/MAV/MRV), for example, are practical models, not measured constants. Grade them honestly (usually B/C) and say so.
- "Set" = one working set taken close to failure (roughly 0–4 reps in reserve). Warm-up sets do not count. Always state this where volume is discussed.
- Volume is expressed as weekly hard sets per muscle unless explicitly stated otherwise.
- Load is expressed as %1RM (percent of one-rep max) and/or a rep range.
- RIR = Reps In Reserve; RPE = Rating of Perceived Exertion (RIR-based, so RPE 8 ≈ 2 RIR).
- 1RM = one-repetition maximum.
- Volume landmarks: MV (maintenance), MEV (minimum effective), MAV (maximum adaptive), MRV (maximum recoverable).
- Use relative Markdown links between pages (
../02-muscle-guides/index.md). These also resolve as Obsidian wikilinks, so the KB is portable. - One concept per file. When a page outgrows a single screenful of scope, split it.
The interconnection contract (Goal 1 — the KB is a network, not a shelf of documents). All of
this is enforced by tools/check-links.mjs; a violation fails the build.
- Two canonical link forms only:
slug.md(same pillar) or../<pillar>/slug.md(another pillar). The app turns exactly these into in-app jumps; any other shape (a deeper path, a differently-cased slug) renders as dead plain text for every app reader. - Cross-links must live in a RENDERED section — TL;DR through Key Uncertainties, or a getting-started page's topic/Related sections. The app strips Backing Data and References entirely, so a link parked there is invisible to users and doesn't count.
- Every page carries ≥2 outbound page links, and every page must be linked to from somewhere (no orphans, no dead ends, one connected graph).
- Link in prose, on meaning. The link belongs on the sentence that already refers to the other idea ("sets taken close to failure"), not in a bolted-on list of related reading. Link liberally — the first mention of any concept another page owns is a link opportunity.
- Every page appears in its pillar's
## Contents(bullet or table format; both are parsed).
Connections compound: tools/graph-core.mjs ranks each page's neighbours by real signals (links
each way, shared citations, shared neighbours) and surfaces them — plus 2-hop "also connected"
pages — in the app's Connected card. Denser honest linking directly improves what readers are
offered next.
- Data files: one instance per file, named by
id(e.g.data/muscles/quadriceps.json).