Skip to content

PromptPotter/prompt-potter-optimizer / .claude/skills/potter-run

potter-run

Verified

Launches (`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.

FileKindSize
SKILL.mdskill md6.0 KB
reference/onboarding.mdmarkdown2.8 KB
---
name: potter-run
description: >-
  Launches (`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.
model: opus
---

# 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](reference/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

1. `.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).
2. `python -m promptpotter dashboard --campaign <id> [--cycle <id>]` (the served dashboard, `--json` for
   the body) + newest `rounds/round_NNNN.json`. Trust its `run_phase`, `pause` and `admission` (the verb
   the cycle admits), never `dashboard.json`'s `declared_phase`.
3. That cycle's `readout.log` tail.

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](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`](../../../docs/operations/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`](../../../docs/methods/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::campaign` and `::pipeline`
  (CHECK a campaign's `pipeline_overlay` against [`datasets.md`](../../../docs/operations/datasets.md) § The model a
  dataset runs). No parameter tweaks unbidden.
- **Warn only from this allowlist**: backend `/status` non-200 or refused (`TERMNORM_ENDPOINTS` in `.env`,
  locally `:8000`); the active pointer naming another dataset than requested; recent
  `measurements/cells/{config_key}.jsonl` with empty `predicted` strings.
- A propagated backend 5xx means halt. **A `⚠ RATE-LIMITED` readout line is told to the operator at
  once**; `✓ … answers again` ends the hold.
- **Never wipe project data without asking**: spell out the full path first.

Stuck-run triage: [`persistence-and-state.md`](../../../docs/operations/persistence-and-state.md) § Diagnosing a live or stuck run.
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: 472kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall