Plans

A plan is proposed work with a paper trail: where it came from, what it is meant to achieve, how simple it is, whether a human approved it, and whether IonWarp was allowed to open a draft PR for it. Alongside plans sit learnings — one-sentence things IonWarp believes about this repo, each with an expiry date, fed into every later review.

Retrieve a plan — GET /api/v1/plans/learning-tests-run-under-bun

curl "https://ionwarp.com/api/v1/plans/learning-tests-run-under-bun" \
  -H "Authorization: Bearer $DASH_API_KEY" \
  -H "Project-ID: pr_acme"

Walk me through plan {id} and what it would change

data_get {
  "collection": "plans",
  "object_id": "learning-tests-run-under-bun"
}

{
  "object": "plan",
  "id": "obj_123",
  "approval_status": "pending",
  "repo_write_status": "not_requested",
  "repo_artifact_path": "repo artifact path",
  "target_outcome": "One retry ladder serves every webhook path.",
  "summary": "Three near-identical retry ladders diverged; collapse them into the shared helper.",
  "created_at": "2026-07-25T12:00:00.000Z",
  "updated_at": "2026-07-25T12:00:00.000Z"
}

Every field is in the plans reference; learnings are learnings — learning, why, learned_at and forgets_at, so a belief about the repo expires instead of hardening into folklore.

The states a plan moves through

status walks discovered → proposed → reviewed → approved → active → completed (or superseded). approval_status is tracked separately as pending / approved / rejected, and requires_approval defaults to true — a plan does not get to skip a human by being confident. Until it is approved, it gets no repo write: the gate is a field on the object, not an instruction in a prompt.

repo_write_mode has exactly one value, draft_pr, and repo_write_status tracks it: not_requested → draft_pr_requested → draft_pr_opened, or failed. source_kind says where the plan came from — repo (a markdown file found in the repository), ionwarp (IonWarp proposed it), or task.

Where plans come from

Discovery is path-based and deterministic: a repo markdown file becomes a plan when it lives under docs/plans/, prds/, or .ionwarp/plans/. Each genuinely new document gets a single-reviewer plan-review chain dispatched against its exact path, so the reviewer bubbles on the Plans page are precise rather than approximate. Re-discovering a plan that already exists changes nothing and creates no duplicate.

study is the pass that does both halves — it discovers repo plans and upserts learnings, and re-runs once 10 PRs have merged since the last one. repeat-failure-learning turns those learnings back into review signal.

A study or discovery pass that cannot run says so by name on the run — read it with Debugging a Run — and a review that could not load learnings continues without them and names the gap rather than pretending it had them.

Next: Reviews for the pipeline plan-review runs on · Repositories & PRs for the repo a plan is written back to.