feat(review): multi-call prompt decomposition roadmap (v0.7–v0.9) — dedicated prompts per pipeline stage, non-agentic

[devops-thiago]

Problem Statement

Post-v0.6.0 direction: move review efficiency forward by decomposing the review flow into more, smaller, dedicated-prompt LLM calls — deterministic orchestration, not agentic — so each call has a predictable size and a single concern.

The orchestration is already multi-call (FindingPipeline.runMultiCall: N batches + per-batch verifier + summary, capped by REVIEW_MAX_AI_CALLS), and FindingVerificationService is already a dedicated second-stage call. What is still "single-shot" is the review call itself: PrReviewPrompts.SYSTEM (~600 lines) makes one call handle 10 review dimensions, severity/confidence calibration, previous-findings reconciliation, suggestions, and the full summary object. Decomposing that mega-prompt — and bounding follow-up rounds by push size instead of PR size — is this roadmap.

Phases

v0.7 — slim the review call (priority)

• feat(review): make the summary call universal and strip the summary object from the review prompt [v0.7] #664 — make the summary call universal; review call returns findings + statuses only
• feat(review): per-batch dimension routing — assemble the review system prompt from only the relevant dimensions [v0.7] #665 — per-batch dimension routing; system prompt assembled from only the relevant dimension blocks

v0.7 — verification correctness

The verification stage lacks the evidence to rule correctly; each ticket is committed to a single approach and they compose rather than overlap:

• feat(review): resolve a finding's cited path:line against the real file before the verifier rules on it #650 — deterministic cited-location resolution: resolve each finding's path:line (quote-search-first) against the real file and hand the snippet to the verifier as established material. No model call.
• feat(review): self-carrying evidence — context-grounded findings quote the material they rest on, and the verifier judges it #475 — self-carrying evidence: context-grounded findings quote the measurement/rule they rest on; the verifier judges the quoted grounding. No new verifier slots, stable inputs as context dimensions grow.

v0.8 — smarter context selection

• feat(review): file triage stage — classify changed files to drive packing order and prompt selection [v0.8] #666 — file triage stage: classification drives packing order, prompt selection, and feeds feat(ai): risk-based model routing and fallback #43 (risk-based model routing)
• feat(review): codebase-aware context beyond the diff (cross-file analysis) #55 — adjacent-file context: deterministic reference extraction + one small selection call + budget-share-bounded injection, fed to reviewer and verifier

v0.9 — predictable follow-up rounds

• feat(review): incremental re-review — review only new commits on synchronize, with a dedicated finding-resolution check [v0.9] #667 — incremental re-review on synchronize + dedicated finding-resolution check call; prompt size bounded by push size

Opt-in / cross-cutting

• feat(review): targeted per-finding verification context — the verifier reads only the material each finding needs [opt-in] #668 — targeted per-finding verification context (the composition point where feat(review): resolve a finding's cited path:line against the real file before the verifier rules on it #650's and feat(review): codebase-aware context beyond the diff (cross-file analysis) #55's material attaches to exactly the finding it belongs to)
• feat(ai): structured outputs — response_format json_schema for JSON-returning calls where the provider supports it #670 — structured outputs (response_format: json_schema) behind a per-model capability flag

Agentic directions (#63 parallel specialists, #57 agentic fix) are post-1.0, opt-in, not currently planned — this roadmap is the non-agentic path; #665 delivers the "dedicated prompt per concern" benefit without agents or tool-calling.

Related open issues, sequenced against this roadmap

Fix before/while landing the decomposition (they live in code these phases restructure):

• Verification silently does not run on ~1/3 of reviews #623 — verification silently not running on ~1/3 of reviews; must be fixed before more stages are modeled on the verifier pattern (feat(review): incremental re-review — review only new commits on synchronize, with a dedicated finding-resolution check [v0.9] #667's resolution check)
• A provider context-length rejection is retried 5x at full price #622 — context-length rejection retried 5× at full price; more calls = more exposure
• pr_purpose is spliced into the summary without MarkdownSafe, breaking its documented invariant #636 — pr_purpose/MarkdownSafe fix must land on the summary-call path, since feat(review): make the summary call universal and strip the summary object from the review prompt [v0.7] #664 moves pr_purpose there
• Coverage banner blames the diff budget for files whose review call failed #655 / Coverage clause drops the legacy omitted-file count when the summary also degraded #659 — disclosure/coverage-clause fixes should land before feat(review): make the summary call universal and strip the summary object from the review prompt [v0.7] #664/feat(review): file triage stage — classify changed files to drive packing order and prompt selection [v0.8] #666 restructure that logic

Made more urgent by this roadmap:

• feat(observability): account for cached and reasoning tokens in cost tracking #28 — cached/reasoning-token cost accounting: the cost model here leans on prompt caching absorbing the fan-out (byte-stable prefixes below); two-bucket pricing will overstate the pipeline's cost and hide whether the decomposition pays off
• feat(review): pluggable per-model tokenizer for exact token counts #239 — per-model tokenizer: estimation error compounds per call once many smaller calls each carry a budget share
• A fresh random fence per call makes budget plans non-reproducible run to run #604 — random fence non-reproducibility also works against stable-prefix caching

Fed by this roadmap:

• feat(ai): risk-based model routing and fallback #43 — risk-based model routing consumes feat(review): file triage stage — classify changed files to drive packing order and prompt selection [v0.8] #666's classifier
• feat(review): incorporate failing CI checks into review context #59 / feat(review): integrate linters and static analysis into reviews #34 / feat(review): detect secrets and risky IaC changes in the diff #60 — deterministic context inputs (CI failures, linters/SARIF, secrets/IaC scan); each should follow the budgeted fenced-section pattern, and their signals can feed feat(review): file triage stage — classify changed files to drive packing order and prompt selection [v0.8] #666's risk tiers

Constraints every stage must respect

• Every AI call goes through ReviewTokenLedger.ensureCallAllowed with usage recorded (streaming via OtelObservabilityListener, blocking via Result.tokenUsage()), or REVIEW_MAX_TOKENS_PER_REVIEW silently breaks.
• DiffBudgetPlanner.plan reserves calls out of REVIEW_MAX_AI_CALLS (currently exactly one, for the summary) — each new stage changes that accounting explicitly.
• Budget overhead estimation concatenates the actual prompt constants (DiffBudgetPlanner.plan, FindingPipeline.clampOverview / budgetedFindingsJson) — every prompt split updates those sites or the budgets become fiction.
• PrReviewPromptsContentTest pins the guidance that past issues fought for; the eval corpus (-Peval) is the recall regression gate. Prompt restructuring lands only with both green, and the risky splits ship behind config gates with the current behavior as fallback.
• Keep system-prompt prefixes byte-stable within a review so OpenAI-compatible prompt caching keeps paying for the multi-call fan-out.

Priority

Important