From ralph-ban
Writes and runs a one-shot consumer program against an importable library (Go, Ruby, TypeScript, etc.) to verify exported API behaviour matches its spec. Useful for end-to-end behavioural verification of a package.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ralph-ban:library-qa [scope of the library change to verify][scope of the library change to verify]The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Write a small consumer that imports the library, calls the API, prints structured output. Run it, parse, judge.
Write a small consumer that imports the library, calls the API, prints structured output. Run it, parse, judge.
Scope: $ARGUMENTS
If no scope was provided, read the recent changeset to determine which exported symbols, types, or behaviours changed.
Load whichever matches the library under test:
references/go.md — GOWORK=off, go run ./scratch/, JSON envelope via encoding/json.references/ruby.md — bin/rails runner vs bundle exec ruby -e, autoload boundaries.references/ts.md — tsx --no-cache, ESM-vs-CJS hazard, tsconfig path mapping.git diff, git log — and identify the surface that changed: exported symbol(s), type signatures, observable behaviour..agent-history/oracle/<card-id>/scratch/ (scratch space, never source). The consumer imports the library, calls the API, and prints structured output..agent-history/oracle/<card-id>/<timestamp>/.Libraries that touch a database, file system, or network need setup before the probe runs:
# 1. Boot whatever the library needs (DB, fixture file, embedded server)
./oracle/boot.sh > "$TXN/boot.log" 2>&1
trap './oracle/teardown.sh' EXIT
# 2. Run the probe
<runner> ./oracle/scratch/probe.<ext> > "$TXN/stdout.txt" 2> "$TXN/stderr.txt"
echo "$?" > "$TXN/exit.txt"
# 3. teardown.sh runs automatically via trap
Setup failure is distinct from spec failure; the boot script's exit code is the discriminator. A probe that hits nil because the DB wasn't migrated tells the Oracle nothing about the library.
Free-text output is fragile — the parser becomes a regex of last resort. Two acceptable forms:
One JSON object per line (newline-delimited JSON, NDJSON):
{"event":"input","value":"abc"}
{"event":"result","ok":true,"id":42}
{"event":"observation","metric":"latency_ms","value":12}
Single JSON object at the end:
... free-form trace lines ...
{"summary":{"id":42,"ok":true,"errors":[]}}
Keep what the probe observed separable from what it printed for humans. The verdict reads the envelope, not the trace.
A probe that mutates shared state is anti-evidence. When the library's API has side effects:
For database side effects, delegate the assertion side to db-state-qa.
Save under .agent-history/oracle/<card-id>/<timestamp>/:
scratch/probe.<ext> — the consumer sourceboot.log — output of any setup scriptstdout.txt / stderr.txt — probe channelsexit.txt — probe exit codeparsed.json — structured envelope after jq extractionverdict.md — APPROVE / REJECT / ESCALATE.agent-history/oracle/<card-id>/scratch/. The probe is not part of the worker's diff.cli-qa — stdout, stderr, exit, separate.GOWORK=off for Go in worktrees, bin/rails runner for Rails-loaded code, tsx --no-cache for TS. Each language's reference file names the gotcha.## Library QA Report
**Scope**: <which library / which exported surface>
**Language**: Go | Ruby | TypeScript | <other>
**Verdict**: APPROVE | REJECT | ESCALATE
### Probe
- Path: `.agent-history/oracle/<card-id>/scratch/probe.<ext>`
- Runner: `<command used>`
- Boot: PASS/FAIL — `<boot.sh exit>`
### Specifications Verified
| Spec # | Probe step | Observed | Verdict |
|--------|------------|----------|---------|
| 1 | (paste from bl show) | (parsed envelope field) | satisfied / unsatisfied / could-not-determine |
### Findings
1. <description with reproduction command and evidence path>
### Transcript
Path: `.agent-history/oracle/<card-id>/<timestamp>/`
Contents: <brief listing>
npx claudepluginhub kylesnowschwartz/ralph-ban --plugin ralph-banRuns lint, type-check, tests, and build checks for Node.js/TS, Python, Rust, Go, Java projects to verify code health after changes.
Verifies code changes by running the app and observing runtime behavior at the user-facing surface (CLI, API, GUI, etc.). Skips tests and typechecking.
Runs active QA verification: executes tests, type checks, linting, builds, debug artifact scans, and git status for JS/TS, Go, Python projects. Reports pass/fail.