feat: add master notebook library scaffolding and review tooling
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.
This commit is contained in:
94
docs/Notebook_Review_Prompt_V1-00.md
Normal file
94
docs/Notebook_Review_Prompt_V1-00.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user