Notebook Proofread

Notebook Proofread Skill

Instructions

1. Determine Scope

Decide which notebooks to process based on the user's request:

• All notebooks (default): Find every .ipynb file in the notebooks/ directory.
• Specific notebooks: Process only the notebooks the user names.

If no notebooks are found, report that and stop.

Always check all notebooks for cross-reference and consistency issues, even if only a subset was explicitly requested — unchanged notebooks can have stale references or new inconsistencies introduced by changes elsewhere.

2. Discover Notebooks and README Files

Use the Glob tool to list all .ipynb files in notebooks/ at runtime. This is the authoritative list of notebooks — never hard-code filenames.

Also locate the README file that describes the notebooks: notebooks/README.md. Read this file — it contains descriptions and links for each notebook and must be checked alongside the notebooks themselves.

Note: The docs/ folder is auto-generated by tox and should NOT be checked or edited.

3. Extract Markdown Cells

For each notebook, read the .ipynb file and examine only markdown cells ("cell_type": "markdown"). Ignore code cells and raw cells entirely.

4. Check Each Notebook

For every markdown cell, check for the following categories of issues:

A. Typos and Spelling

• Flag misspelled words.
• Use UK English spellings as the standard:
  • "colour" not "color", "favour" not "favor"
  • "-ise" endings preferred: "organise", "specialise", "recognise" (not "-ize")
  • "-our" endings: "behaviour", "neighbour"
  • "-re" endings: "centre", "metre" (but "meter" for measuring instruments is acceptable)
  • "-ence"/"-ance" where UK differs: "defence", "licence" (noun), "practise" (verb)
  • "whilst", "amongst" are acceptable but not required
• Do NOT flag domain-specific terms, function/class/variable names, or library names as typos. Use judgement for medical and data-science terminology.

B. Grammar and Style

• Check for grammatical errors (subject-verb agreement, tense consistency, dangling modifiers, etc.).
• Follow UK punctuation conventions (e.g. single quotes for quotation marks in prose, full stops and commas outside closing quotation marks unless part of the quoted material).
• Flag passive voice only when it makes meaning unclear; passive voice is acceptable in technical writing.

C. Inconsistencies

• Terminology: Flag cases where the same concept uses different names across cells or notebooks (e.g. "patient snapshot" vs "patient-level snapshot" vs "snapshot" used interchangeably without definition).
• Formatting: Inconsistent heading levels, list styles (mixing bullet and numbered lists for similar content), or emphasis patterns (bold vs italic for the same purpose).
• Capitalisation: Inconsistent capitalisation of domain terms (e.g. "Emergency Department" vs "emergency department").

D. Repetition

• Flag paragraphs or sentences that convey the same information already stated in the same notebook.
• Note if a concept is re-explained at length when a brief cross-reference would suffice.

E. Cross-References

• Check any mention of another notebook (by name, number, or description) against the actual list of .ipynb files discovered in step 2.
• Flag references to notebooks that do not exist.
• Flag references where the notebook number/letter is correct but the description is wrong (e.g. referring to "notebook 2a" as "Predict using patient snapshots" when it is actually "Create patient snapshots").
• Flag broken markdown links to other notebooks.

5. Check the README Files

Apply the same checks (A–E above) to notebooks/README.md. In addition:

• Completeness: Verify that every notebook discovered in step 2 is listed in the README, and that no README entry refers to a notebook that no longer exists.
• Descriptions: Check that the description next to each notebook link matches what the notebook actually covers (compare against the notebook's title and opening markdown cells).
• Links: Verify that all links point to valid paths/URLs and use the correct file extension.

6. Report Findings

Produce a report for each notebook and README with issues, grouped by category. Use this format:

## <notebook filename>

### Typos and Spelling
- Cell N: "recieve" → "receive"
- Cell N: "behavior" → "behaviour" (UK English)

### Grammar
- Cell N: "The data are processed and then it is stored" — mixed singular/plural reference to "data".

### Inconsistencies
- Cell N uses "patient snapshot" but Cell M uses "patient-level snapshot" — pick one and use consistently.

### Repetition
- Cell N repeats the explanation of X already given in Cell M.

### Cross-References
- Cell N: References "notebook 3a" as "Evaluate group snapshots" but 3a is "Prepare group snapshots" (3b is "Evaluate group snapshots").

Omit any category that has no issues for a given file.

7. Summary Table

After the per-file reports, provide a summary:

8. Offer Fixes

After reporting, ask the user whether they want you to apply fixes. If yes:

• Fix typos and spelling automatically.
• For grammar, inconsistencies, and cross-references, propose the fix and apply it after confirmation.
• Use the EditNotebook tool to make changes in notebook cells; use the StrReplace tool for README files.
• Do NOT modify code cells.

Source: UCL-CORU/patientflow — distributed by TomeVault.