| name | precision-medicine-doc-audit |
| description | Audits all Markdown files in the precision-medicine-mcp repo against four canonical principles: (A) server Python code is the authoritative tool count, (B) server-registry.md is the authoritative server/tool summary, (C) all three patient outcomes (PAT001/PAT002/PAT003) must be represented consistently, (D) no content block may appear in more than one MD file (DRY). Use this skill whenever a new version of the platform ships, a new server is added, a new patient use case is validated, or before any major doc update. Trigger phrases: "audit the docs", "check docs are correct", "doc cleanup", "canonical check", "are the docs up to date", "DRY check on markdown".
|
Precision Medicine MCP — Doc Audit Skill
Purpose
After every platform version update, run this audit to catch stale numbers,
missing patient references, and repeated content before they spread further.
The audit has four checks (A–D) that map directly to the four canonical principles.
Run them in order: A feeds B, and B+C together surface D violations.
Step 1 — Run the automated audit script
The bundled script does the mechanical work. Run it from the repo root:
python .claude/skills/doc-audit/scripts/audit.py 2>&1 | tee /tmp/doc-audit-report.txt
The script outputs a structured report with four sections. Read the output — it
will tell you exactly which files have violations and what the correct values are.
If the script is not yet installed (first run), see Installation below.
Step 2 — Interpret the four check sections
Check A — Tool counts: code vs registry
The script greps @mcp.tool() in every servers/mcp-*/src/*/server.py and
compares to the count in docs/reference/shared/server-registry.md.
A violation means: someone added or removed a tool in Python code but forgot
to update the registry table. The server code is always right; update the registry.
Check B — Hardcoded counts: all MD files
The script greps all *.md files for patterns like \d+ (custom )?server,
\d+ tool, \d+-server, all \d+ server, then flags any file that isn't
docs/reference/shared/server-registry.md itself.
A violation means: a doc is stating a count directly instead of pointing at
the registry. The fix is one of:
- Replace with:
see [Server Registry](../reference/shared/server-registry.md)
- Or if a specific count is needed for context, verify it matches the registry
and add a note:
(N as of vXX — see registry for current count)
Check C — Three patient outcomes: completeness and accuracy
The script checks two things:
- Completeness: Any MD file that mentions one or two patient IDs but not all
three is flagged (unless it's a patient-specific file like
PAT003_OVERVIEW.md).
- Accuracy: Any file that states a numeric outcome for PAT001, PAT002, or PAT003
is checked against the canonical values below.
Canonical patient outcome values (update this section when fixtures change):
| Patient | Metric | Canonical value | Source file |
|---|
| PAT001 | TMB (POLE-corrected) | 47.3 mut/Mb | tests/fixtures/pat001_canonical.py |
| PAT001 | Top neoantigen IC50 | 7.8 nM | tests/fixtures/pat001_canonical.py |
| PAT001 | HRD score | 54 | tests/fixtures/pat001_canonical.py |
| PAT001 | CAF fraction | 18.2% | tests/fixtures/pat001_canonical.py |
| PAT002 | HRD score | 35 | tests/fixtures/pat002_canonical.py |
| PAT003 | Reynolds risk | 14.3% | tests/fixtures/pat003_canonical.py |
| PAT003 | Framingham risk | 12.0% | tests/fixtures/pat003_canonical.py |
| PAT003 | ASCVD risk | 10.3% | tests/fixtures/pat003_canonical.py |
| PAT003 | hsCRP | 1.8 mg/L | tests/fixtures/pat003_canonical.py |
A violation means: a doc states an outcome that differs from the canonical
fixture. The canonical fixture (which matches the live server output) is always
right — update the doc.
Check D — DRY: duplicate content blocks
The script extracts paragraph-length text blocks (>80 words) from every MD file
and computes fingerprints. Any fingerprint appearing in more than one file is
flagged with both locations.
A violation means: the same content block lives in two places. One must
become the canonical location and the other must be replaced with a link.
Standard fix pattern:
<!-- was: [full text of the repeated block] -->
> For PAT001 findings see [Patient Outcomes Reference](../reference/shared/patient-outcomes.md#pat001).
The canonical single-source for patient outcome narratives is:
docs/reference/shared/patient-outcomes.md
If that file doesn't exist yet, create it before resolving D violations — see
Creating patient-outcomes.md below.
Step 3 — Generate the fix prompt
After reading the audit output, generate a targeted Claude Code fix prompt.
Use this template:
# Doc Cleanup — [version] audit findings
## Violations found
[paste the audit report table here]
## Fix instructions
For each B violation:
Find: [exact stale count string]
Replace: [link to server-registry.md or corrected count]
For each C violation:
Find: [wrong numeric value]
Replace: [canonical value from audit table]
For each D violation:
In [secondary file]: replace [repeated block] with link to [canonical file#anchor]
## Verification
grep -rn "[old count]" [affected files]
# Expected: zero matches
Creating patient-outcomes.md (one-time setup)
If docs/reference/shared/patient-outcomes.md does not exist, create it before
resolving any D violations. It should contain exactly three sections, one per
patient, each with:
- One-sentence clinical profile
- What standard workup found (and its limitations)
- What the platform found that standard workup missed (3 bullets max)
- Canonical numeric outcomes (linked to the fixture file)
Keep each section under 200 words. Other docs link to the relevant anchor
(#pat001, #pat002, #pat003) rather than restating the findings.
Installation (first run only)
Copy the skill into the repo:
mkdir -p .claude/skills/doc-audit/scripts
cp <this-skill-directory>/SKILL.md .claude/skills/doc-audit/SKILL.md
cp <this-skill-directory>/scripts/audit.py .claude/skills/doc-audit/scripts/audit.py
git add .claude/skills/doc-audit/
git commit -m "chore: add doc-audit skill for canonical reference checks"
The script has no dependencies beyond the Python standard library.
Quick reference: the 4 principles
| # | Principle | Source of truth | Fix when violated |
|---|
| A | Code is canonical for tool counts | servers/mcp-*/src/*/server.py | Update registry to match code |
| B | Registry is canonical for counts in docs | docs/reference/shared/server-registry.md | Replace inline count with registry link |
| C | Three patients, consistent outcomes | tests/fixtures/pat00X_canonical.py | Update doc to match fixture value |
| D | No repeated content blocks | Designated canonical file per topic | Keep in one place; replace others with link |
