# Dental AI Skills — Project Instructions

## What This Repo Is

A collection of AI skills (structured markdown protocols) for dental professionals. Each skill is a `SKILL.md` file that gives AI models (Claude, GPT, etc.) specialized dental knowledge and output formats.

## Skills

| Skill | Folder | Purpose |
|-------|--------|---------|
| Dental Author Disclosures | `dental-author-disclosures/` | Dated, sourced register of author and sponsor relationships. No score, no inference of bias from a name, a talk or a membership. |
| Research Critic | `research-critic/` | Single-paper appraisal (PICO, bias tools in native formats, dental-specific red flags, claim-to-evidence map, Study Credibility score). Single-paper, internal-credibility focused. |
| Clinical Evidence Reviewer | `clinical-evidence-reviewer/` | Body-of-evidence reviews with runtime-aware retrieval mode, PICO, GRADE certainty **per critical outcome**, guideline vs expert-consensus distinction, citation policy with uncertainty labels. |
| Dental Evidence Retriever | `dental-evidence-retriever/` | Literature-search workflow (PICO → PubMed/Cochrane/guideline-body/registry strategies → retrieval log). Honest about runtime — no fabricated citations. |
| Dental Paper Fetch | `dental-paper-fetch/` | Gets the free full-text PDF and figures of a paper by PMID, DOI, PMCID or title. Legal open-access sources only. Reports paywalled papers with their link. No way around paywalls or bot checks. |
| Dental Statistical Forensics | `dental-statistical-forensics/` | Deep numerical audit (SD/range, CIs, effect sizes, MCID, individual predictability, unit-of-analysis errors, clustering, multiplicity, missing data, measurement reliability, model appropriateness). |
| Dental Evidence Report Artifact | `dental-evidence-report-artifact/` | Converts completed evidence analysis into HTML/PDF-ready reports without adding new scientific claims. |
| Dental Content Creator | `dental-content-creator/` | Audience-aware dental content with platform adaptations and no-overclaim guardrails. |
| Dental Image Generator | `dental-image-generator/` | AI-generated clinical illustrations and patient visuals via Google Gemini. |

### Literature-skill workflow

```
PMID, DOI or title →  dental-paper-fetch  →  full-text PDF and figures for the skills below
                       (free legal copies only; paywalled papers reported with their link)

Clinical question  →  dental-evidence-retriever  →  clinical-evidence-reviewer
                       (search strategy + log)        (GRADE per outcome, guidelines)
                                      ↘ numerical audit → dental-statistical-forensics

Single paper       →  research-critic  →  dental-statistical-forensics
                       (Study Credibility)    (numbers, SD/CI/MCID, model validity)
                                      ↘ funding and relationships → dental-author-disclosures
                                        (sourced register, no score)

Completed analysis → dental-evidence-report-artifact
                      (HTML/PDF-ready report, teaching artifact)
```

The literature skills hand off to each other automatically when the user crosses from search, to appraisal, to numerical audit, to clinical recommendation, to artifact presentation.

## Rules for Contributing

- Do not change the output schema of any skill without updating the README and TESTING.md.
- Every clinical claim in a skill's instructions must be defensible — no unsourced absolutes.
- Keep skills focused: one job per skill. Literature skills can exceed ~150 lines because the protocols are non-trivial, but they must still pass the "one job" test.
- **Citation honesty is non-negotiable.** Skills that demand citations must also branch on whether retrieval is actually possible in the runtime. No fabricated DOIs/PMIDs.
- **Bias-tool fidelity.** Use each tool's native judgment categories — do not force AMSTAR 2, Newcastle-Ottawa, QUADAS, JBI into RoB 2's "Low / Some concerns / High" labels.
- **Numerical honesty is non-negotiable.** Distinguish statistical significance, effect magnitude, precision, dispersion, measurement error, clinical threshold, and individual predictability. Never claim "predictable" clinical outcomes from a favorable mean alone.
- Validate skill metadata before pushing:
  ```bash
  python3 scripts/validate_skills.py
  ```
- Run smoke tests before pushing:
  ```bash
  python3 scripts/smoke_test_repo.py
  ```
- Run the relevant manual tests in TESTING.md before pushing changes.
- Keep `agents/openai.yaml` metadata aligned with each skill's `SKILL.md`.
- Prefer minimal diffs and clear commit messages.
- Methodology updates (case definitions, appraisal tools, guideline-body URLs, GRADE handbook revisions) require updating the "Methodology Review Date" block at the bottom of the affected skill.

## Francisco Summary (final response format)

- Close finished work with the **Francisco Summary** block defined in `~/.claude/CLAUDE.md`: 🧑‍⚕️ what this means in plain terms, 🙋 what you need to do, 🤖 what an agent can do without you, 💡 what I propose, and a 🟢/🟡/🔴 flag. It goes first in the final response, not last, and is skipped on quick answers and lookups.