PromptPotter/prompt-potter-optimizer / .claude/skills/potter-run
potter-run
VerifiedLaunches (`new` / `resume`), supervises and diagnoses PromptPotter campaigns, and onboards a new dataset. Fires on "/potter-run", "start a campaign", "run promptpotter-self", "resume", "watch it", "how's the run", "why did round N do that", a dataset named to optimize, or a campaign already in flight that needs supervising.
potter-run — launch, supervise, diagnose
Argument (optional): a dataset name (the account's .promptpotter/projects/{tenant}/datasets/ over the
shipped promptpotter/assets/datasets/), a raw file path (onboarding.md), or nothing.
Mode — declare it in the entry line, never ask
- bug-hunting (default): the run is an INSTRUMENT; the deliverable is the bug. Signals:
promptpotter-self/justlogic/d234, a dirty tree, "why", "what broke". Read past the headline into the round's LLM I/O; halt, fix at the root (default: potter's optimizer prompts,promptpotter/assets/optimizers/potter/pipeline.yaml), relaunch within the autonomy mode. - campaign-supervision: the RESULT is the deliverable. Signals: a tenant dataset, a fresh ingest, "just watch it". Report and interpret; touch no prompt, config or code; never kill the run.
Entry — re-read from disk every time
.promptpotter/projects/{tenant}/.workspace/active_session.json→ the LATEST launch only; parallel runs:python -m promptpotter cycles --attached(--inside <campaign>::<cycle>for an L4 inner run's).python -m promptpotter dashboard --campaign <id> [--cycle <id>](the served dashboard,--jsonfor the body) + newestrounds/round_NNNN.json. Trust itsrun_phase,pauseandadmission(the verb the cycle admits), neverdashboard.json'sdeclared_phase.- That cycle's
readout.logtail.
Then one line: mode · what's live · next action. Nothing before it. Node I/O:
GET …/rounds/{n}/audit. Hand a result on with export --tier <chat|report|notebook|deploy|package>.
| State | Go to |
|---|---|
| A run is in flight | Supervise |
| Nothing live, dataset named | Launch |
| A finished round named / "why did it do that" | Read a round |
| A raw file, a new tenant dataset, or a cold machine | reference/onboarding.md |
Launch
Who launches is the autonomy mode's call. Never block a foreground shell on a campaign
(promptpotter-self is the exception: /potter-self). Verbs and flags:
persistence-and-state.md and --help; a dataset's defaults
are {dataset}/dataset.yaml::campaign, never guessed. head-to-head mints every arm in one act;
price-head-to-head <plan> prices one at $0. pause is the HALT; a queued launch takes
cancel-queued <job_id> (machine-status names it).
Every ending states its next verb (the readout's cli: line). set-limits answers the caps as
ARMED, each against its own book (ArmedCaps, also dashboard's caps): a raise past the account
allowance says armed $X (asked $Y, allowance), and the spend counter is the CAMPAIGN's, cumulative
across resumes and cycles. A hard
kill loses nothing: every query lands in measurements/cells/{config_key}.jsonl at once.
Supervise
Self-firing cadence (~150–270 s), each wake a full reading pass (/potter-self § Live-run supervision).
Check node health before calling a round healthy: the round's health (grade, cause,
dominant_node, node_failure_rates) and per-sample step_statuses. Cause evidence_starved, or one
node dominating the failure rates, makes the measurement noise: HALT — "Evidence node {dominant_node}
is down (failed on {pct}% of samples) — a backend fault, not a prompt problem. Fix the backend and resume."
A defect visible in the ORIGIN cell is a halt trigger when it will recur: candidates producing no
measurement (repeat_variant, answer-collapse), optimizer calls blowing max_tokens, a drifting panel, a
prompt growing every round. Halt, fix the root, relaunch; wave one through only when it is cell-specific,
and say which.
Read a round
ROUND {N} COMPLETE
Winner: C{x}/{total} — {acc}% ({delta} vs prev best)
Layer: {L1/L2/L3} Patience: {x}/{max} Queries: {evaluated} Cache: {hit_rate}%
CRITIQUE: {2-4 key lines — what failed, what to try next}
NEXT: {continue L1 / escalate to L2 / etc.}
Finished cycle: campaigns/<id>/log.md and cycles/<id>/index.json (final.stop_reason: label, outcome
and next step come from STOP_REASON_INFO; compose no other).
A held potter round is not proof the candidate failed
(candidate-elimination.md): a tail of 1s is the difficulty
ORDER, never a surge; p_better (buy more?) and improved (adopt?) can disagree, neither broken — on
improved: false read the final paired_breakdown in the ledger's race_standing records, report both,
never retune epsilon; a vs_reference rate where panel.scored < panel.expected is not a standing.
Style
- The operator acts on the first line: a sentence, a compact box, or 3–5 bullets. Interpret; never dump CLI output.
- Configs are the source of truth:
{dataset}/README.md,{dataset}/dataset.yaml::campaignand::pipeline(CHECK a campaign'spipeline_overlayagainstdatasets.md§ The model a dataset runs). No parameter tweaks unbidden. - Warn only from this allowlist: backend
/statusnon-200 or refused (TERMNORM_ENDPOINTSin.env, locally:8000); the active pointer naming another dataset than requested; recentmeasurements/cells/{config_key}.jsonlwith emptypredictedstrings. - A propagated backend 5xx means halt. A
⚠ RATE-LIMITEDreadout line is told to the operator at once;✓ … answers againends the hold. - Never wipe project data without asking: spell out the full path first.
Stuck-run triage: persistence-and-state.md § Diagnosing a live or stuck run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |