RFD 085: Query Explain

• Status: Discussion
• Category: Design
• Authors: Jean Mertz git@jeanmertz.com
• Date: 2026-05-12

Summary

Add an --explain flag to jp query that prints the rendered system prompt, the resolved tools, the resolved attachments, and the new user query that would be sent to the LLM, then exits without calling the provider. Output is structured and JSON-first via --format json.

Motivation

JP composes the next request to the LLM from many sources: workspace config, conversation deltas, CLI flags, tool directives, attachments, and the user's query. By the time a turn is sent, the user often can't easily tell what the assistant is seeing. Common questions:

• Which tools is the assistant getting this turn, and with what parameter schemas?
• What does the fully rendered system prompt look like after persona, instructions, and overrides have merged?
• Which attachments are attached, and where are they coming from?
• Is the query template rendering the way I think?

Today, answering these requires reading provider logs, instrumenting the code, or guessing. --explain makes the assembled request inspectable in one command. Because the output is structured, it composes with jq and scripts.

Design

User experience

A single boolean flag, no companion flags:

jp q -c architect --explain "my query"
jp q -c architect --explain --format json "my query"

Behavior:

• Assembles the full request the same way jp q would — including MCP server startup, tool schema resolution, and attachment fetching — then exits before calling the provider.
• --explain implies --no-persist. No conversation events are persisted, no title is generated in the background, and locking is delegated to NullLockBackend.
• Echoes the rendered system prompt and its sections, the enabled tools (name, description, JSON Schema), the attachment list (source + title), and the new user request.
• Not a dry-run. Request assembly performs its usual side effects: MCP server startup, MCP tool/resource calls, HTTP fetches, file reads, and command-attachment execution. These are real, and exactly what the executed path performs. Only the conversation state and the LLM provider call are skipped. Resolution failures abort the preview, same as a normal query.

The flag composes naturally with every existing jp q flag (-m, -r, --tool, -a, --cfg, -%, etc.). The mental model is "set up the query you'd run, then flip a flag to see what it would be."

Output schema (v1)

{
  "schema_version": 1,
  "system": {
    "prompt": "...",
    "sections": [
      :
        "title": "...",
        "tag": "...",
        "content": "..."
      }
    ]
  },
  "tools": [
    {
      "name": "fs_grep_files",
      "description": "Search through the project's files.",
      "parameters": {
        "/* JSON Schema */": ""
      },
      "source": "local"
    }
  ],
  "attachments": [
    {
      "source": "file:///path/to/file.md",
      "title": "file.md"
    }
  ],
  "request": {
    "content": "my query",
    "schema": null
  }
}

title on an attachment is a best-effort display label: Attachment.description if set, otherwise derived from the URL's last path segment, otherwise the raw source.

description on a tool is ToolDocs::schema_description() — the same string providers send in the tool schema (the tool's summary if set, otherwise its description). The preview shows what the assistant sees, not a richer internal docs field.

source on a tool follows ToolSource's serialization: builtin, local, or mcp for the common cases; dotted forms (local.<tool>, mcp.<server>, mcp.<server>.<tool>) when the source overrides the name in config.

Text rendering walks the same struct: a header per section, the system prompt rendered as markdown, tools listed with their descriptions and parameter schemas as fenced JSON blocks, attachments as a labeled list, and the user query in a quoted block. The text renderer reuses existing components where possible: SectionConfig::render() for system sections, ToolDefinition::to_parameters_schema() for schemas, the markdown renderer in jp_md, and the format-aware printer.

Architecture

--explain implies --no-persist. The implication is wired in startup, not inside Query::run — by the time Query::run is reached, load_workspace has already chosen the persist and lock backends. The mechanism is a Commands::implies_no_persist() -> bool method (default false) consulted by run_inner before load_workspace; Query returns self.explain. This matches the existing Commands::conversation_load_request() pattern for declarative per-command information needed at startup.

The effective persist value (cli.globals.persist && !cli.command.implies_no_persist()) is computed once and written back to cli.globals.persist before Ctx::new runs. From that point on, both load_workspace and every downstream consumer of ctx.term.args.persist (notably the title-generation branch in Query::run) see the same value, so persist-gated logic doesn't need separate !self.explain guards. The longer-term overlap between the persist flag and the NullPersistBackend type is a known redundancy worth consolidating in a separate refactor; 085 does not depend on that consolidation.

The branch itself short-circuits in Query::run after chat_request stamping but before the editor echo block — the block that renders the user's freshly edited request via TurnView::render_user_request. Skipping the echo prevents it from emitting non-JSON text to stdout under --format json, and is sound because the preview already contains the request body. By that point in the flow, everything the preview needs is already available locally:

• Vec<ToolDefinition> from tool_definitions(...), including fully resolved MCP tool schemas. MCP servers are started by configure_active_mcp_servers earlier in Query::run, independently of persistence.
• Vec<Attachment> resolved by the attachment handlers.
• The final ChatRequest after stdin / query / template / editor / schema / author processing.
• The system prompt (cfg.assistant.system_prompt) and rendered sections (build_sections(&cfg.assistant, !tools.is_empty()), the same call build_thread makes).
• The per-tool config (cfg.conversation.tools), which lets the preview recover each tool's source — tool_definitions erases that field by the time it returns Vec<ToolDefinition>.

The explain branch reads these values, builds a QueryPreview, prints it via the format-aware printer, and returns. On success, it also removes the editor query file (QUERY_MESSAGE.md) if one was created by the editor path — matching the cleanup the executed path performs after handle_turn. Both paths use the same tool_definitions, attachment resolution, and build_sections helpers with the same upstream inputs. The executed path rebuilds the thread inside run_turn_loop once the new request is added to the stream; the explain path renders its preview from the same inputs. The preview omits conversation history, which is the only place the two snapshots differ.

As an incidental cleanup, the pre-turn build_thread(...) call currently in Query::run is removed. Today it produces a Thread only consumed for its attachments field — handle_turn only reads &thread.attachments, and run_turn_loop rebuilds the thread itself. After this RFD, attachments flows directly into handle_turn, and the explain branch constructs its preview inputs locally.

pub(crate) async fn run(self, ctx: &mut Ctx, handle: Option<ConversationHandle>) -> Output {
    // ... existing setup: lock, MCP, build_conversation, tools, attachments,
    //     sanitize, chat_request stamping ...

    if self.explain {
        let preview = QueryPreview::from_parts(
            &cfg, &tools, &attachments, &chat_request,
        );
        let result = print_preview(&ctx.printer, &preview);
        if let Some(path) = query_file
            && result.is_ok()
        {
            fs::remove_file(path)?;
        }
        return result;
    }

    // ... editor echo (renders the user's freshly edited request) ...

    let turn_result = self.handle_turn(/* ..., &attachments, ... */).await;
    // ...
}

QueryPreview derives Serialize. The shape is versioned via schema_version so future changes can evolve without breaking existing consumers.

JSON output passes the preview to print_json. The current helper accepts &serde_json::Value; this RFD widens it to accept T: Serialize. Text output is a single render function over the struct.

Drawbacks

• Adds a flag to a command that already has many. jp q --help grows. Mitigated by clear short-help text.
• Maintenance contract on the JSON shape. Every future change to what gets sent must consider whether to surface the change in the preview and how to evolve the schema. This is the cost of making the request inspectable; the benefit is debuggability for users and AI agents alike.

Alternatives

jp query show subcommand. Ruled out by the existing CLI shape. jp q's trailing positional query: Option<Vec<String>> consumes any non-flag tokens as the query body, so jp q show ... parses show as the query text, not as a subcommand. Reshaping jp q to free up subcommand space is a much larger change than this feature warrants.

jp prompt print (or jp request print) as a peer command. Cleanly separates concerns, but the user must rewrite their jp q invocation in a different form to inspect it. The whole point of the feature is "I have this command, what would it actually do?" — making the user re-type it elsewhere is friction with no architectural payoff. Discoverability is also worse: a user inside jp q --help looking for inspection finds a flag, not a sibling command.

Multiple scope flags (--show-tools, --show-system, ...). Adds CLI surface area for filtering that JSON consumers can do trivially with jq. If filtering proves useful, add it later as a value on the existing flag (--explain=tools,system) without breaking the boolean form.

Showing history contents. Considered and rejected. jp c print already renders conversation history with rich style and turn-selection flags; duplicating that surface would drag scope-modifier flags (--last N, --turn N) onto jp q for a job that is already done well elsewhere. Use jp c print directly when prior turns matter.

Extracting a build_query function as the single source of truth. Earlier drafts proposed pulling the request-building logic out of Query::run into a pure function called by both the executed and explained paths to prevent drift. Once history contents were dropped from the preview, the only work left to share was the system prompt + tools + attachments + new request — all of which Query::run already produces in locals before handle_turn. Short-circuiting there reuses the same locals directly, so the extra function buys nothing.

Wire-format preview. Each provider serializes the request differently (Anthropic blocks, OpenAI messages, Gemini parts). --explain operates on JP's abstract representation, which is stable and provider-agnostic. Wire-level preview is a separate concern with a different audience and can be added later as e.g. --wire-explain without conflict.

Non-Goals

• History contents. jp c print already shows conversation history with rich style flags. Use it directly when prior turns matter.
• Attachment content. The preview lists attachments by source and title. To inspect content, use jp a print <url>.
• Wire-format preview. Out of scope — see Alternatives.

Risks and Open Questions

• JSON schema stability. Once shipped, downstream scripts will depend on the field names (Hyrum's Law). The schema_version field is the safety valve. Document the schema in the user-facing docs alongside --explain so the contract is explicit from day one.
• System prompt rendering parity. Parity is structural: both paths use the same cfg.assistant.system_prompt value and the same build_sections(&cfg.assistant, !tools.is_empty()) call. The executed path rebuilds the thread inside run_turn_loop once the new request is added to the stream; the explain path renders its preview from the same upstream inputs. The preview omits history, which is the only place the two snapshots differ.
• --explain is not side-effect-free. Attachment and tool resolution run exactly as on the executed path, including command-attachment execution, HTTP fetches, and MCP server startup. Neither path is expected to write to caches or workspace state during resolution; any handler that does is a separate bug, not unique to this feature.
• Session activation under --no-persist. Today, --no-persist (and therefore --explain) still writes the terminal session's active-conversation mapping — load_workspace swaps the persist and lock backends to null variants, but not the session backend. Users running jp q --explain --id X will observe their session's active conversation change to X. This is a pre-existing gap in --no-persist, tracked separately; This RFD inherits the behaviour rather than fixing it inline.

Implementation Plan

1. Widen print_json to accept T: Serialize. One-line trait bound change plus call-site updates. Independent of this feature and reviewable on its own.
2. Add Commands::implies_no_persist(). A method on Commands (default false) consulted by run_inner to compute the effective persist value, which is then written back to cli.globals.persist before Ctx::new so ctx.term.args.persist mirrors it. load_workspace and every downstream consumer of the flag see the same value. Matches the existing Commands::conversation_load_request() pattern. Independent of this feature.
3. Add the --explain flag on Query and the short-circuit branch.Query::implies_no_persist() returns self.explain, so persistence is forced off before workspace setup. The branch sits in Query::run after chat_request stamping but before the editor echo block, and removes the editor query file on success (matching the executed path's post-handle_turn cleanup). As an incidental cleanup, the pre-turn build_thread(...) call (only used today to pass thread.attachments into handle_turn) is removed; attachments flows directly into handle_turn.
4. Define QueryPreview and supporting types. Derive Serialize. Version via schema_version. Build it from &cfg, Vec<ToolDefinition>, Vec<Attachment>, and ChatRequest — &cfg carries the system prompt input and the per-tool source lookup.
5. Add the text and JSON renderers. Text path reuses SectionConfig::render(), jp_md, ToolDefinition::to_parameters_schema, and the format-aware printer. JSON path passes QueryPreview to the widened print_json.
6. Tests. Snapshot tests for both text and JSON output across fixture configurations.
7. Documentation. A feature page under docs/features/ describing the flag and the schema (with schema_version: 1 called out).

Phases 1 and 2 are independent and can land first. Phases 3–6 depend on them. Phase 7 follows merge.