Plans

A plan is a proposed change to your repository. IonWarp finds plans in the repository's docs or writes its own, and each plan records where it came from, what it should achieve, how it scored, whether a person approved it, and whether IonWarp opened a draft pull request for it. Next to plans are learnings: one-sentence facts IonWarp has learned about the repository, each with an expiry date, which later reviews read.

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; a learning stops being used after its forgets_at date.

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. Until a plan is approved, IonWarp writes nothing to the repository for it.

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

A markdown file in the repository becomes a plan when it lives under docs/plans/, prds/, or .ionwarp/plans/. Each new document gets one plan-review run against its exact path. Finding 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 says so.

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