Skip to main content

Recursive Planning

The planner loop is the heart of Paddles. It gives a small model the ability to investigate a workspace iteratively instead of guessing from its training data.

The Loop​

Each cycle follows a clear rhythm:

  1. Assemble interpretation context
  2. Planner selects next bounded action
  3. Controller validates against schema and budget
  4. Execute the action safely
  5. Append outputs into loop state
  6. Check: is evidence sufficient?
  7. If yes, synthesize. If no, loop back.

The model drives direction. The controller ensures safety.

Action Vocabulary​

The planner expresses its intentions through a constrained action schema:

ActionPurpose
answerSynthesize now — evidence is sufficient
searchFind relevant files or content in the workspace
list_filesDiscover candidate files by pattern
readRead a specific file or artifact
inspectExamine read-only workspace state
shell / diff / editExecute concrete workspace modifications
refineSharpen a search query based on prior results
branchSplit an investigation into parallel subqueries
stopRequest synthesis with current evidence

These are not suggestions the model can ignore. Each action has a schema the controller validates before execution.

Search and Retrieval Contract​

search and refine actions are the retrieval contract boundary:

  • search starts a bounded workspace query using the configured gatherer backend.
  • refine reruns retrieval with a new query using the same gatherer contract and current loop context.

Both actions stream evidence through gatherer progress and summary events so the operator can observe query execution while the planner keeps looping.

Key retrieval constraints are documented in Search and Retrieval.

Budget Enforcement​

Every planner session runs within a bounded budget:

  • Step limit — maximum number of planner iterations
  • Tool budget — maximum number of tool executions
  • Evidence budget — maximum items in the evidence bundle

When any budget is exhausted, the loop stops and synthesis proceeds with whatever evidence has been gathered. This prevents runaway investigation while still allowing deep multi-step reasoning.

Steering-Signal-Guided Decisions​

The planner is not left alone once evidence starts to accumulate. The controller applies steering signals that bias the loop toward more intelligent moves.

SignalWhat it changes
Action biasAdds a planner review note that biases edit-oriented turns toward likely file action instead of repeated broad retrieval
Premise challengeAdds a planner review note when sources start to outweigh the original premise, so the planner must refine, stop, or continue explicitly
Compaction cueKeeps retained context small enough to stay actionable
Budget boundaryTerminates recursion when the hard caps are reached

Two premise-challenge cases matter most:

  1. Quiet-step refinement If the loop has gathered evidence but several steps add nothing new, the controller refreshes interpretation context before asking the planner again.
  2. Premise judgement If the user says "CI is failing" but the gathered sources show only success, cancelled, or an unconfirmed in_progress run, repeating gh run list --limit 20, then --limit 10, then --limit 5 is not intelligent work. The controller should stop and make synthesis judge those sources directly.

Deterministic Edit Target Resolution​

Edit-oriented turns now pass through a deterministic resolver before the loop keeps broad-searching or attempts a workspace mutation. The resolver self-discovers authored workspace paths, respects the repository .gitignore boundary when present, and produces one of three explicit outcomes:

  • Resolved — one authored path won the ranking and can move into read, diff, or edit actions.
  • Ambiguous — multiple authored candidates remain viable, so the turn must narrow further instead of guessing.
  • Missing — no safe authored target matched the hint, so the controller fails closed and replans instead of mutating the wrong file.

This is a convergence tool, not a full IDE intelligence layer. It does not depend on editor state and it does not promise complete semantic symbol resolution. Its purpose is narrower: keep edit-oriented turns inside safe, authored workspace paths and make misses explainable.

Compaction Planning Today​

As the planner accumulates evidence across many steps, the working context can grow large. A compaction engine evaluates the planner's retained evidence and produces a structured compaction plan.

That interface is shaped for recursive self-assessment, but the current adapters still rely mostly on bounded heuristics rather than a fully model-judged compaction pass.

Low-value artifacts are pruned from working context, but their content remains reachable through typed locators pointing to the transit tier. This keeps the active context tight without losing depth.