palladium/docs/Notebook_Review_Prompt_V1-00.md

Notebook Review Prompt v1.0.0

The canonical LLM review prompt for a Palladium master notebook. Model-agnostic: paste everything below the line into any capable LLM together with the notebook's raw .ipynb JSON, or run it in-repo with /review-notebook <path>. It hunts the class of problems deterministic checks can't: content oddities, cross-cell rot, stale numbers, and stage leakage.

---

Role

You are reviewing one Palladium master notebook — a Mercury-served Jupyter deliverable a client will see on a live call. Your input is the raw .ipynb JSON (cell sources, tags, outputs, in document order). Before judging anything, read the contracts it was built against:

• docs/Mercury_Notebook_Pattern_V1-00.md — reactivity, gate, stage/backstage, appendix
• docs/Assessment_Pattern_V1-00.md or docs/Study_Pattern_V1-00.md — whichever matches the master's type (assessments/… vs studies/…)
• The master's own README.md and, for cross-checks, its engine package (discoverylib/, teicalc/, …) — you MAY open engine .py files to verify a claim, and should when a number or name is in doubt.

What NOT to re-check

tests/test_notebooks.py already enforces these deterministically — do not spend review effort or findings on them: the file parses as nbformat 4; kernel is python3; no error outputs; execution counts are monotonic top-to-bottom; the unique tags (topic-bank, engagement-data, gate, data-appendix) appear at most once; notebook-first masters have all four, the appendix last, engagement-data above the widgets; presentation cells emit no stream output; content cells use no magics.

Check catalogue

Work cell by cell in document order, then once more end-to-end per theme:

1. Content oddities — typos and grammar in client-visible text; duplicated or near-duplicate prompts/items; terminology drifting from the source document the content anchors (the README names it); key slugs that don't match their titles; counts/minutes in comments or prose that don't match the actual content; tone that doesn't belong in front of a client. Spot it by: reading the content cells as an editor, then recounting anything a comment or heading claims.
2. Broken cross-cell references — names used before their defining cell in document order; a widget's .value read in the cell that defines it (frozen at first render); variables shadowed or redefined with a different meaning; cells that only work because of stale kernel state (would fail on a fresh top-to-bottom run); imports used but not imported in any earlier cell. Spot it by: tracing each name in a cell back to its defining cell index.
3. Stale numbers — figures hardcoded in markdown or annotations that the engine or gate could contradict; outputs inconsistent with the current source (a changed cell whose committed output still shows the old result); gate pins that disagree with the test-suite pins; totals in prose that don't equal the content. Spot it by: comparing markdown claims ↔ committed outputs ↔ gate asserts ↔ engine constants.
4. Tag/metadata issues — content sitting in an untagged cell (invisible to tests and the export pipeline); a cell whose comment says one thing and whose tag says another; presentation logic inside a content cell or vice versa. Spot it by: asking, for each cell, "who consumes this — and would they find it?"
5. Stage leakage — anything client-inappropriate reachable on the Mercury stage: markdown cells ALWAYS render on stage, so internal notes/instructions in markdown are leaks; diagnostics via bare print instead of backstage(); placeholder or internal wording in the board/stage HTML; a filled engagement value where the master should have a placeholder. Spot it by: simulating the stage — markdown cells + non-backstage outputs of code cells are what the client sees.
6. Export quality — appendix JSON missing state a figure or table shows; values that won't JSON-serialize; the .md handoff missing something an LLM would need to draft the write-up; preamble claims that don't match the document. Spot it by: reading the appendix cell's payload against everything rendered above it.

Output format

Report findings ordered by severity, one line each, exactly:

[BLOCKER]    cell <index> (<tag or first source line>): <finding> — <evidence> — <suggested fix>
[SHOULD-FIX] cell <index> (<tag or first source line>): <finding> — <evidence> — <suggested fix>
[NIT]        cell <index> (<tag or first source line>): <finding> — <evidence> — <suggested fix>

• BLOCKER — a client would see something wrong, or the notebook lies (stale number, stage leak, broken reference).
• SHOULD-FIX — correctness/maintainability debt that won't embarrass anyone today.
• NIT — polish.

End with one verdict line: VERDICT: <n> blocker(s), <n> should-fix, <n> nit(s) — <one-sentence overall judgement>. If a theme produced no findings, do not pad — finding nothing is a valid result; say No findings. above the verdict if the whole review is clean. Output nothing outside this format.