feat: Add interactive judgment loop to ce:review

Overview

Redesign ce:review's Interactive mode post-review flow. The current single bucket-level policy question (Review and approve specific gated fixes / Leave as residual work / Report only) gets replaced with a four-option routing question (Review walk-through / LFG / File tickets / Report only). The Review path walks findings one at a time with plain-English framing and per-finding actions (Apply / Defer / Skip / LFG the rest). The LFG, File-tickets, and LFG-the-rest paths show a compact plan preview (Proceed / Cancel) before executing. Defer actions file tickets in the project's tracker (reasoning-based detection with GitHub Issues or harness task primitive as fallback).

A small framing-guidance upgrade to the shared reviewer subagent template ensures every user-facing surface — the walk-through, bulk preview, and ticket bodies — explains findings in plain English, observable behavior first, not code structure. The upgrade applies universally across all 16+ persona agents via a single file change, fixing both the null-why_it_matters schema violations observed in adversarial and api-contract and the code-structure-first framing observed in correctness and maintainability.

All other ce:review modes (Autofix, Report-only, Headless) and the existing merge/dedup pipeline, persona dispatch, and safe_auto fixer flow remain unchanged.

Problem Frame

Today's Interactive mode mostly degrades into rubber-stamping or wholesale deferral:

1. Judgment calls are hard to make. When a finding needs human judgment, today's pipe-delimited table row rarely gives enough context to decide confidently. The user is asked to approve or defer a bucket of findings they haven't individually understood.
2. High-volume feedback is unreason-able. A review with 8-12 findings turns into a scrolling table. There's no way to respond to individual items meaningfully — only to "approve the whole bucket" or "defer the whole bucket."

The result: the gated_auto / manual routing tiers exist in the schema but are never actually exercised per-finding in practice. See origin document for the full problem frame.

Requirements Trace

Routing after safe_auto fixes

• R1. Four-option routing question replaces today's bucket-level policy question (see origin)
• R2. Zero-findings path skips the routing question and shows a completion summary
• R3. Routing question names the detected tracker inline only when detection is high-confidence
• R4. Four options: Review each finding one by one..., LFG. Apply the agent's best-judgment action per finding, File a [TRACKER] ticket per finding..., Report only...
• R5. Routing option C is a batch-defer shortcut — distinct from the walk-through's per-finding Defer

Per-finding walk-through

• R6. Walk-through presents findings one at a time in severity order with a position indicator
• R7. Per-finding question content: plain-English problem, severity, confidence, proposed fix, reasoning
• R8. Per-finding options: Apply / Defer / Skip / LFG the rest
• R9. Advisory-only findings substitute Acknowledge — mark as reviewed for option A
• R10. Override = pick a different preset action; no inline freeform custom fixes
• N=1 adaptation: walk-through wording adapts and LFG the rest is suppressed

LFG path

• R11. LFG applies the per-finding action the agent would recommend; top-level scope vs. walk-through D scope distinction
• R12. Single completion report with required fields after any LFG execution

Bulk action preview

• R13. Compact preview with Proceed / Cancel before every bulk action (LFG, File tickets, LFG the rest)
• R14. Preview content grouped by intended action; one line per finding in compressed framing-quality form

Recommendation tie-breaking

• R15. When reviewers disagree on per-finding action, synthesis picks the most conservative using Skip > Defer > Apply

Defer behavior and tracker detection

• R16-R21. Defer files tickets in project's tracker; minimal reasoning-based detection; fallback to GitHub Issues then harness task primitive; failure surfaces inline; no-sink omits Defer entirely; internal .context/ todo system explicitly out of fallback chain

Framing quality (cross-cutting)

• R22-R26. All user-facing finding surfaces (walk-through questions, LFG completion reports, ticket bodies, bulk-preview lines) explain in plain English, observable-behavior-first, tight 2-4 sentences. Planning resolves: delivered by a small framing-guidance upgrade to the shared reviewer subagent template (Unit 2), applied once at the source rather than rewritten downstream. Per-persona file edits beyond the shared template are deferred as follow-up.

Mode boundaries

• R27. Only Interactive mode changes behavior. Autofix / Report-only / Headless unchanged
• R28. Final-next-steps flow (push / PR / exit) runs only when one or more fixes landed in the working tree

Scope Boundaries

• No new ce:fix skill. All changes live inside ce:review.
• No changes to the findings schema, merge/dedup routing beyond the recommended-action tie-breaking in R15, or autofix-mode residual-todo creation.
• Small framing-guidance updates to the shared reviewer subagent template are in scope (see Unit 2). Per-persona file edits are out of scope for v1 — the shared-template change affects all personas at once, which is deliberately the "small upgrade" chosen over a synthesis-time rewrite pass.
• No inline freeform fix authoring in the walk-through — the walk-through is a decision loop, not a pair-programming surface.
• The "approve intent, write a variant" case is unsupported in v1; user picks Skip and hand-edits.
• No changes to Autofix, Report-only, or Headless mode behavior.
• The pre-menu findings table format (pipe-delimited, severity-grouped) stays unchanged.
• The current bucket-level policy question wording is removed entirely — no backward-compatibility shim.

Deferred to Separate Tasks

• Per-persona file edits beyond the shared template: deferred. Unit 2 updates the shared subagent template to add R22-R25 framing guidance, which applies universally to all personas. If post-ship sampling shows specific personas still produce weak framing, targeted per-persona file upgrades land as follow-up.
• Phasing out the internal .context/compound-engineering/todos/ todo system and the /todo-create, /todo-triage, /todo-resolve skills: long-term direction acknowledged in origin. Separate cleanup.
• Script-first architecture for the tracker defer dispatch and bulk preview rendering: considered during planning. Deferred to v2 — current ce:review is entirely prose-based orchestration; adding new scripts expands redesign footprint and cross-language test surface. Re-evaluate after usage data.

Context & Research

Relevant Code and Patterns

Current ce:review structure to modify:

• plugins/compound-engineering/skills/ce-review/SKILL.md — single orchestrator, 744 lines. After Review section at lines 603-715 is the primary edit target.
• Current bucket policy question at plugins/compound-engineering/skills/ce-review/SKILL.md:615-640. The stem violates AGENTS.md third-person rule ("What should I do...") — the redesign fixes this.
• Stage 5 merge pipeline at plugins/compound-engineering/skills/ce-review/SKILL.md:451-479. Existing "most conservative route" rule at line 471 is extended for R15.
• Headless detail-tier enrichment at plugins/compound-engineering/skills/ce-review/SKILL.md:568-572. The walk-through reuses this exact matching rule verbatim.
• Safe_auto fixer dispatch at plugins/compound-engineering/skills/ce-review/SKILL.md:664-671 ("Spawn exactly one fixer subagent..."). The walk-through's Apply actions accumulate and dispatch at the end of the walk-through to preserve this "one fixer, consistent tree" guarantee.
• Findings schema at plugins/compound-engineering/skills/ce-review/references/findings-schema.json. No schema changes; R15 tie-breaking operates on existing fields.

Patterns to mirror:

• Four-option menu format: plugins/compound-engineering/skills/ce-ideate/references/post-ideation-workflow.md:137-150. Front-loaded distinguishing words, self-contained labels, third-person agent voice.
• Per-item walk-through with progress header: plugins/compound-engineering/skills/todo-triage/SKILL.md:20-29. Uses numbered chat prompts; the ce:review walk-through must upgrade to AskUserQuestion.
• Per-agent review loop with Accept / Reject / Discuss: plugins/compound-engineering/skills/ce-plan/references/deepening-workflow.md:195-216.
• Pipe-delimited findings table rhythm for the pre-menu: plugins/compound-engineering/skills/ce-review/references/review-output-template.md.

AGENTS.md rules that materially shape this plan:

• plugins/compound-engineering/AGENTS.md:122-134 — Interactive Question Tool Design (4-option cap; self-contained labels; third-person agent voice; front-loaded distinguishing words; target-named when ambiguous)
• plugins/compound-engineering/AGENTS.md:117-119 — Cross-platform question tool phrasing. Every new question uses "the platform's blocking question tool (AskUserQuestion in Claude Code, request_user_input in Codex, ask_user in Gemini)" plus a fallback path.
• plugins/compound-engineering/AGENTS.md:109-114 — Rationale discipline. Extract the walk-through, bulk preview, and tracker defer flows to references/ because they are conditional (Interactive mode only) and would otherwise add ~200 lines to every invocation.
• plugins/compound-engineering/AGENTS.md:155-165 — Platform-specific variables in skills. The walk-through state file path is pre-resolved from the existing run-id pattern.

Institutional Learnings

• docs/solutions/skill-design/compound-refresh-skill-improvements.md — Phrase interactive-question-tool references as platform-agnostic ("AskUserQuestion in Claude Code, request_user_input in Codex") with explicit "stop to wait for the answer" language. Gate new interactive surfaces on explicit mode:interactive (the existing default), never on "no question tool = headless" auto-detection.
• docs/solutions/skill-design/beta-promotion-orchestration-contract.md — Mode contracts are load-bearing. tests/review-skill-contract.test.ts asserts the ce:review mode surface; any behavior change must ship the contract test update in the same PR.
• docs/solutions/workflow/todo-status-lifecycle.md — Apply outcomes in Interactive mode must continue routing through the existing ready todo pipeline (preserving the downstream-resolver contract). Defer routes to the new tracker path. Skip produces no downstream artifact. Do not invent a new pending-producing path.
• docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md — Stateful per-item walkthroughs need explicit transitions. The walk-through's "no more findings" and "LFG the rest" are distinct terminal transitions; encode each explicitly rather than collapsing.
• docs/solutions/best-practices/codex-delegation-best-practices-2026-04-01.md — Skill body size is a multiplicative cost driver. Move Interactive-mode detail to references/ because it runs on a minority of invocations.
• docs/solutions/skill-design/pass-paths-not-content-to-subagents-2026-03-26.md — If Defer invokes a sub-agent for ticket composition, pass paths (to merged findings artifact) rather than content. Also: "per-item walk" phrasing can cause 7x tool-call amplification in Claude Code vs. "bulk find, then filter" phrasing — the walk-through spec iterates over merged findings in memory, not by re-scanning per finding.

External References

None used. Local patterns are strong; no framework/security/compliance unknowns.

Key Technical Decisions

• Extract walk-through, bulk preview, and tracker defer to references/ files. SKILL.md is already 744 lines; these three surfaces are conditional (Interactive mode, when gated/manual findings remain) and would inflate the body by ~200 lines paid on every invocation. Respects plugins/compound-engineering/AGENTS.md:109-114.

• R15 tie-breaking extends the existing Stage 5 "most conservative route" rule. The rule at SKILL.md:471 already does this for autofix_class / owner. R15 adds the same discipline for the recommended action (Apply / Defer / Skip), using order Skip > Defer > Apply. Same Stage 5 sub-step, same philosophy — no new architectural seam.

• R22-R25 framing quality is delivered by a small framing-guidance upgrade in the shared reviewer subagent template, not a synthesis-time rewrite pass. Planning-phase sampling of 15+ recent review artifacts across 5 personas showed two distinct gaps:

  1. Consistency gap: adversarial-reviewer and api-contract-reviewer produced why_it_matters: null on every finding in at least one recent run (schema violation — field is required).
  2. Quality gap: correctness-reviewer and maintainability-reviewer populate why_it_matters but lead with code-structure-first framing; observable-behavior-first (R23) failed in roughly 5 of 7 sampled findings.

  Considered options: (a) synthesis-time rewrite pass (new Stage 5b with per-finding model dispatch) — rejected as over-engineered for the gap, adds recurring per-review cost, and papers over a schema violation rather than fixing it; (b) per-persona file upgrades across 5 personas — rejected as scope inflation for v1; (c) shared-template upgrade — chosen. One file change (the persona subagent template) adds framing guidance that every dispatched persona receives, fixing both gaps at the source with bounded scope. If post-ship sampling shows specific personas still fail, targeted per-persona edits land as follow-up.

• Apply actions in the walk-through accumulate and dispatch at the end. The walk-through collects Apply decisions in memory, and after the loop exits, dispatches one fixer subagent for the full accumulated set. Trade-off the user experiences: a fix failure surfaces at the end of the walk-through, not at the decision moment. The alternative — per-finding fixer dispatch — costs per-finding fixer overhead, spawns racey mid-walk-through processes, and complicates the user model (when is the Apply "real"?). The unified end-of-walk-through dispatch also means the fixer sees the whole set at once and can handle inter-fix dependencies (two Applies touching overlapping regions) in one pass rather than sequentially. The existing Step 3 fixer prompt needs a small update to acknowledge the heterogeneous queue (gated_auto + manual mix, not just safe_auto); tracked in Unit 3.

• Tracker detection stays reasoning-based per R14 / R17. No enumerated checklist of