Robert Helewka
a967f73d09
Add CLAUDE.md defining the Palladium master notebook conventions and Red Panda Approval criteria, plus a review-notebook slash command for LLM-driven notebook review. Expand .gitignore to block client/engagement documents and generated exports, keeping masters client-clean while allowing text/image sources. Normalize slider widget numeric values from floats to integers in notebook JSON.
95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# 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.
|