Skip to content

Routes and Decisions

Jump to bottom
Your GitHub Name edited this page Jun 17, 2026 · 5 revisions

Routes and Decisions

PromptPilot's harness chooses what should happen before a frontier coding agent runs. Every developer prompt the harness sees gets one of four route values in the SLM's execution spec.

Route types

Route (spec value) Use when Result
clarify The request is ambiguous or underspecified Ask one focused question and stop
answer The request does not need code execution Offer a direct SLM reply (opt-in via --let-slm-answer); otherwise forward to the coding agent
passthrough Transformation risk is high Send the raw prompt to the coding agent unchanged
act Coding work is needed Forward to the coding agent (Codex / Claude-style). The SLM produces a downstream_prompt that preserves constraints and sharpens the original

These map 1:1 to the route field on the SLM's ExecutionSpec JSON (emitted by the v2 normalizers slm-anthropic-v2 / slm-openai-v2 for API keys and slm-subscription-v2 for Max OAuth / ChatGPT — the default slm backend auto-selects the v2 normalizer matching whichever auth you have). The legacy v1 normalizers (slm-anthropic / slm-openai / slm-subscription) carry only the INTENT: header in a prose envelope and so always resolve to act/answer — clarify and passthrough exist only in the v2 JSON format — the auto-selected default on every backend. The downstream coding agent always receives plain text either way — see SLM Harness → Output format for the side-by-side example.

The README demo poster shows this clarify → act flow end to end on a real slm-anthropic-v2 run.

Autonomous degrade: clarify → act (v0.3.1)

A clarify route emits a human-style clarifying question as the downstream prompt. That is the right behavior interactively — but an autonomous coding agent has no human to answer it, so it answers the question instead of acting, producing a silent end-state failure. In the chain_auth benchmark this dropped slm_native v2 to 2/5 (a 60% failure rate) pre-fix.

v0.3.1 (PR #39) adds a shared helper resolve_downstream() in prpt/core/spec.py. When the route is clarify and the environment variable PROMPTPILOT_AUTONOMOUS=1 is set, it degrades the route to act: it returns the original imperative and resets the now-stale spec (route/intent → act, scope → localized, memory_record → the original). The helper is called by all three v2 normalizers (slm-openai-v2, slm-anthropic-v2, slm-subscription-v2), by the cli --auto / --dry-run paths, and by the optimize_prompt hook.

Alongside the guard, SYSTEM_JSON_SPEC was tightened so clarify fires only for genuine ambiguity about what to change — never merely because a file or location is unstated (a repo-access agent can grep).

Result: with the guard on, end-state is restored to 5/5. Interactive CLI behavior is unchanged — the degrade is off by default, so a human still sees the clarify question.

The mis-fire is model-specific: on an actionable imperative, gpt-5.4-nano mis-fired 20/20, while gpt-5.4-mini mis-fired 0/20 and claude-haiku-4-5 0. The smallest SLM over-clarifies; the guard neutralizes it.

Rewrite is a behavior, not a route

When the route is act, the SLM produces a rewritten downstream_prompt alongside the spec. "Rewrite" is therefore not a separate routing decision — it's the default work the SLM does inside act. Older drafts of these docs listed Rewrite as its own route; that conflated the route (where the prompt goes) with the transformation (what the prompt looks like when it gets there).

Tool-output compression is a different subsystem

Compression of noisy tool output (pytest, grep, git diff, installer logs, ...) is not a route the harness picks for the user's prompt. It runs as a separate PostToolUse hook against the coding agent's bash tool output, after the tool runs. See Tool Output Compression for the wiring and what the regex-based compression preserves.

Decision criteria

The SLM should consider:

  • Is the user asking for code changes, explanation, setup, or troubleshooting?
  • Are there explicit constraints, non-goals, files, commands, tests, or stack traces?
  • Would rewriting remove important context? (If yes — route to passthrough.)
  • Would a clarification question prevent wasted work? (If yes — clarify.)
  • Can a direct answer satisfy the request without invoking the coding agent? (If yes — answer.)
  • Otherwise — act, with a constraint-preserving rewrite.

Examples

These examples are schematic. The real wire format is the JSON ExecutionSpec; the human-readable rendering below shows the decision shape.

Clarify:

Input: "Fix auth."
Route: clarify
Question: Which auth failure should I focus on: login, token refresh, or permission checks?

Passthrough:

Input: "Fix this production migration. Do not change the public schema contract."
Route: passthrough
Reason: High-risk database/API constraints should reach the coding agent unchanged.

Act (with rewrite):

Input: "Fix the failing auth test. Keep the public API stable and do not touch migrations."
Route: act
downstream_prompt: Fix the failing auth test without changing public API behavior or migration files.
Preserve: failing auth test, public API stability, no migration edits.

See also: SLM Harness · Semantic Preservation · Tool Output Compression

Clone this wiki locally