| name | check-pipeline |
| description | Check that a code and its Pipeline/ .md are still compatible — that every symbol, cell number, data file, and data-flow claim in the pipeline doc still matches the current code (drift detection). Use after editing a documented notebook/engine/script, before trusting a pipeline doc, or on request ("does the pipeline still match the code?"). Reports mismatches (missing symbols, wrong cell numbers, renamed functions, changed I/O) and can update the doc. Companion to /write-pipeline. |
/check-pipeline — verify a code matches its pipeline doc
Pipeline docs drift when the code changes: a function gets renamed, a cell is inserted (shifting all
later cell numbers), a data file is dropped, an I/O contract changes. This skill compares a
Pipeline/*.md against the current source and reports every mismatch, so the map stays trustworthy.
When to use
- Right after editing a documented code.
- Before relying on a pipeline doc you didn't just write.
- On request: "is the pipeline still accurate?", "check the codes match the pipelines".
- Across the board (no argument): check every
Pipeline/*.md against its code.
Method
1. Pair each pipeline doc with its code. The doc's header names it ("Code: path/to/").
Read the header, or scan the folder if checking everything.
2. Dump the code to readable text (same helper the writer uses):
python3 .claude/skills/write-pipeline/dump_code.py "$SCRATCH" "path/to/<file>"
3. Extract the doc's checkable claims and verify each against the dump:
- Symbols (every name in the "Key symbols" table and in prose code-spans): does it still appear
in the code?
grep -F 'symbolName' the .full.txt (or source). Flag any that are absent
(renamed/removed) — the highest-value drift signal.
- Cell numbers: for each
| Symbol | Cell N | row, confirm the symbol's definition is at/near
cell N in <base>.outline.txt (±2 tolerates minor insertions; larger shifts = flag "cell numbers
stale, N inserted/removed above"). If many rows are off by a constant, an insert/delete happened —
report the offset and the pivot cell.
- Data files: every input/output file the doc says is loaded/written — does the code still
read/write it, and does the file exist on disk (
ls)?
- Upstream/downstream links: the "Inputs/outputs" section names producers/consumers — spot-check
those still hold (e.g. the doc says stage B consumes symbol
X from stage A; grep that X is
still built the way the doc claims).
- Copied-layer coupling: if the doc says "this section is copied verbatim from
<other code>",
diff the copied definitions against the source — silent divergence there is a real correctness
risk, not just doc drift.
4. Report. Produce a compact verdict per doc:
Pipeline/<doc>.md vs <code>
OK: 24/27 symbols present, cell numbers within ±1, all data files load.
DRIFT:
- symbol `oldName` (row "…", cell 42) NOT FOUND — renamed to `newName`?
- cell numbers off by +3 from cell 130 onward (3 cells inserted at ~128).
- doc says it writes results.csv — no such write in code, file absent.
Classify each finding: BROKEN (symbol/file gone, math claim contradicted) vs STALE (cell
numbers shifted, wording outdated but still correct). Do not rewrite the code to match the doc — the
code is ground truth; the doc follows it.
5. Offer to fix the doc. If the user approves (or asked for --fix), update the pipeline .md
in place: correct cell numbers, rename symbols, fix I/O. For a large rewrite, hand off to
/write-pipeline. Never "fix" by editing the code.
Guardrails
- The code is authoritative; a mismatch means the doc is wrong — UNLESS the code change was
itself a mistake. If a documented guardrail was silently removed from the code, flag it as a
possible regression rather than quietly updating the doc to match.
- A doc citing a symbol that no longer exists is worse than a stale cell number — rank BROKEN first.
- Cell-number drift is expected and cheap to fix; don't over-alarm on ±1–2.
- Report; only edit the doc with approval or an explicit
--fix.
