ce-doc-review Autofix and Interaction Overhaul

Overview

Overhaul ce-doc-review to match the interaction quality and auto-fix leverage of ce-code-review (post-PR #590). Today, ce-doc-review surfaces too many findings as "needs user judgment" when one clear fix exists, nitpicks at low confidence, and ends with a binary question that forces re-review when the user wants to apply fixes and move on. This plan expands the autofix classification from binary (safe_auto / manual) to three tiers (safe_auto / gated_auto / manual) using ce-code-review-aligned names, raises and severity-weights the confidence gate, ports the per-finding walk-through + bulk-preview + routing-question pattern from ce-code-review, adds in-doc deferral, introduces multi-round decision memory, rewrites learnings-researcher to handle domain-agnostic institutional knowledge, and expands the ce-compound frontmatter problem_type enum to absorb the best_practice overflow. Advisory-style findings (low-confidence observations worth surfacing but not worth a decision) render as a distinct FYI subsection of the manual bucket at the presentation layer rather than a separate schema tier.

The plan ships in phases so lower-risk foundation work (enum expansion, agent rewrite) can land and stabilize before the interaction-model port. Each implementation unit is atomic and can ship as its own PR.

Problem Frame

See origin document for full problem framing. In brief, a real-world review surfaced 14 findings all routed to manual, including five P3s at 0.55–0.68 confidence, three concrete mechanical fixes that a competent implementer would arrive at independently, and one subjective observation with no right answer. Under the revised rules the same review produces 4 auto-applied fixes, 1 FYI entry, 4 real decisions, and 5 dropped — the user engages with 4 items instead of 14.

Requirements Trace

38 requirements from the origin document. Full definitions live there; listed here for traceability.

• Classification tiers: R1–R5 (three tiers — add gated_auto; keep safe_auto / manual; advisory-style findings become presentation-layer FYI subsection of manual, not a distinct enum value)
• Classification rule sharpening: R6–R8 (strawman-aware rule with safeguard, consolidated promotion patterns, shared framing-guidance block)
• Per-severity confidence gates: R9–R11 (P0 0.50 / P1 0.60 / P2 0.65 / P3 0.75; drop residual promotion; low-confidence manual findings surface in a distinct FYI subsection without being dropped)
• Interaction model: R12–R16 (4-option routing, per-finding walk-through, bulk preview, tie-break)
• Terminal question: R17–R19 (three-option split: apply-and-proceed / apply-and-re-review / exit)
• In-doc deferral: R20–R22 (append to ## Deferred / Open Questions section)
• Framing quality: R23–R25 (observable consequence, why-the-fix-works, tight)
• Cross-cutting: R26–R27 (AskUserQuestion pre-load, headless preservation)
• Multi-round memory: R28–R30 (cumulative decision primer, suppression, fix-landed verification)
• learnings-researcher agent rewrite: R36–R42 (domain-agnostic, <work-context>, dynamic category probe, optional critical-patterns read) — benefits /ce-plan's existing usage
• Frontmatter enum expansion: R43 (add architecture_pattern, design_pattern, tooling_decision, convention)

Dropped from scope: R31–R35 (learnings-researcher integration into ce-doc-review). See Key Technical Decisions and Alternative Approaches Considered for the rationale. In scope: R36–R42 (learnings-researcher domain-agnostic rewrite, Unit 2) and R43 (frontmatter enum expansion, Unit 1), which benefit /ce-plan's existing usage even though learnings-researcher is not dispatched from ce-doc-review.

Scope Boundaries

• Not introducing external tracker integration. Document-review's Defer analogue is an in-doc section.
• Not changing persona activation/selection logic. The 7 personas and their conditional activation signals stay as-is.
• Not adding requires_verification or a batch fixer subagent. Document fixes apply inline.
• Not addressing iteration-limit guidance. "After 2 refinement passes, recommend completion" stays.
• Not persisting decision primers across interactive sessions (matches ce-code-review walk-through state rules).
• Not redesigning the frontmatter schema dimensions. Enum expansion only — no new learning_category field alongside problem_type.

Deferred to Separate Tasks

• Frontmatter validation test. Adding a pre-commit or CI check that enforces problem_type enum membership is valuable (correctness-gap slipped through today) but is additive and can ship as a follow-up.
• Updating the frontmatter component enum. It's heavily Rails-focused and would benefit from expansion for non-Rails work, but that's out of scope for this overhaul.

Context & Research

Relevant Code and Patterns

Port-from targets (ce-code-review):

• plugins/compound-engineering/skills/ce-code-review/references/walkthrough.md — per-finding walk-through (terminal output block + blocking question split, fixed-order options, (recommended) marker, LFG-the-rest escape, N=1 adaptation, unified completion report)
• plugins/compound-engineering/skills/ce-code-review/references/bulk-preview.md — grouped Apply/Filing/Skipping/Acknowledging preview with Proceed / Cancel
• plugins/compound-engineering/skills/ce-code-review/references/subagent-template.md:51-73 — framing-guidance block for personas
• plugins/compound-engineering/skills/ce-code-review/SKILL.md:75 — AskUserQuestion pre-load directive
• plugins/compound-engineering/skills/ce-code-review/SKILL.md:477 (stage 5 step 7b) — recommendation tie-break order Skip > Defer > Apply > Acknowledge

Target surfaces (ce-doc-review):

• plugins/compound-engineering/skills/ce-doc-review/SKILL.md — orchestrator
• plugins/compound-engineering/skills/ce-doc-review/references/subagent-template.md — framing-guidance block lands here
• plugins/compound-engineering/skills/ce-doc-review/references/synthesis-and-presentation.md — tier routing, confidence gate, decision primer, and headless envelope updates
• plugins/compound-engineering/skills/ce-doc-review/references/findings-schema.json — autofix_class enum expansion
• plugins/compound-engineering/agents/document-review/ce-*.agent.md — 7 persona files (mostly unchanged)

Caller contracts:

• plugins/compound-engineering/skills/ce-brainstorm/SKILL.md:188-194 — invokes interactively on requirements doc
• plugins/compound-engineering/skills/ce-brainstorm/references/handoff.md:29,56,65 — surfaces residual P0/P1 adjacent to menus; offers re-review
• plugins/compound-engineering/skills/ce-plan/references/plan-handoff.md:5-17 — phase 5.3.8; interactive normally, mode:headless in pipeline

Schema surfaces:

• plugins/compound-engineering/skills/ce-compound/references/schema.yaml (canonical) and yaml-schema.md (human-readable) — problem_type enum definitions + category mapping
• plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml and yaml-schema.md — duplicate copies, must update in sync
• plugins/compound-engineering/skills/ce-compound/SKILL.md — author steering language
• plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md — refresh steering language

Agent to rewrite:

• plugins/compound-engineering/agents/research/ce-learnings-researcher.agent.md — domain-agnostic rewrite

Test surfaces:

• tests/pipeline-review-contract.test.ts:279-352 — asserts ce-doc-review is invoked with mode:headless in pipeline mode. Will need extension for new tier visibility in headless envelope.
• tests/converter.test.ts:417-438 — OpenCode 3-segment → flat name rewrite for ce-doc-review agent refs. Unaffected.
• No dedicated test file for ce-doc-review itself. Adding one is in scope (Unit 8).

Institutional Learnings

Seven directly applicable learnings from docs/solutions/:

• docs/solutions/best-practices/ce-pipeline-end-to-end-learnings-2026-04-17.md — Mandatory read. Authored from the ce-code-review PR #590 redesign this plan ports. Documents the bulk-preview vs. walk-through distinction, the 4-option AskUserQuestion cap as a structural constraint, the "two semantic meanings in one flag" risk, and the "sample 10-20 real artifacts before accepting research-agent architectural recommendations" rule.
• docs/solutions/skill-design/compound-refresh-skill-improvements.md — Six-item skill-review checklist (no hardcoded tool names, no contradictory phase rules, no blind questions, no unsatisfied preconditions, no shell in subagents, autonomous-mode opt-in). The "borderline cases get marked stale in autonomous mode" template informs how advisory findings behave in headless runs.
• docs/solutions/skill-design/research-agent-pipeline-separation-2026-04-05.md — Classifies learnings-researcher as ce-plan-owned (HOW / implementation-context). Drove the decision to remove R31–R35 from scope entirely: rather than dispatch from ce-doc-review in any form (always-on or conditional), keep the agent in its ce-plan pipeline lane. ce-doc-review does not dispatch it. Users who want institutional memory should invoke ce-plan.
• docs/solutions/skill-design/pass-paths-not-content-to-subagents-2026-03-26.md — Default to path-passing; 7× tool-call difference from prompt phrasing. Relevant to Unit 2's learnings-researcher rewrite — the <work-context> input should pass paths and compressed context, not full documents.
• docs/solutions/skill-design/beta-skills-framework.md + beta-promotion-orchestration-contract.md + ce-work-beta-promotion-checklist-2026-03-31.md — Beta-skill pattern for major overhauls. Considered and rejected for this work (see Alternative Approaches below).
• docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md — High severity for this plan. Model tier/confidence/deferral as an explicit state machine; re-read state at each transition boundary. Directly shapes Unit 4 (synthesis pipeline) structure.
• docs/solutions/skill-design/discoverability-check-for-documented-solutions-2026-03-30.md — When enum expands, update instruction-discovery surface (schema reference, learnings-researcher prompt, AGENTS.md) in the same PR. Shapes Unit 1 and Unit 2.

External References

No external research was needed — the work is internal plugin refactoring with strong local patterns (ce-code-review post-PR #590 is the canonical reference).

Key Technical Decisions

• Port the ce-code-review walk-through / bulk-preview pattern rather than invent a new one. Same menu shape, same tie-break rule, same AskUserQuestion pre-load pattern. Users who've experienced ce-code-review's new flow will find ce-doc-review consistent. Tier naming aligned with ce-code-review (safe_auto, gated_auto, manual) so cross-skill mental model is consistent.
• Three tiers, not four — advisory is a display treatment, not an enum value. ce-code-review has four tiers (adds advisory) because code reviews have a meaningful "report-only, release/human-owned" category (rollout notes, residual risk, learnings). Document reviews rarely produce that shape — FYI observations are typically just low-confidence manual findings that don't need a decision. Collapsing to three tiers + FYI-subsection presentation drops a schema value without losing the user-facing distinction between "needs decision" and "FYI, move on." Cognitive load lower; schema simpler.
• Interaction-surface convergence with ce-code-review is intentional; keep the skills separate. Post-plan, ce-doc-review and ce-code-review share interaction mechanics (walk-through shape, bulk preview, routing question, tie-break order) but evaluate genuinely different things: the personas are different (coherence/feasibility/scope-guardian for docs vs correctness/security/performance for code), the inputs are different (prose vs diff), and the failure modes are different. Shared interaction scaffold, distinct review content. Unifying into one skill would smear the focused-review value each delivers today.
• Ship without a ce-doc-review-beta fork. See Alternative Approaches.
• Do not dispatch learnings-researcher from ce-doc-review at all. The agent is ce-plan-owned (implementation-context per research-agent-pipeline-separation-2026-04-05.md). When ce-doc-review runs inside ce-plan, the agent has already fired and its output lives in the plan. When ce-doc-review runs inside ce-brainstorm, the context is WHY (product-framing), not HOW (implementation) — running an implementation-context agent would be a pipeline violation. When ce-doc-review runs standalone, the personas already cover coherence, feasibility, and scope — institutional memory is a nice-to-have that adds dispatch cost without proportional value. Users who want institutional memory for a doc should invoke /ce-plan, where that lookup is a first-class pipeline stage.
• Put R1–R8 classification changes in the shared subagent template, not in each persona. One file edit propagates to all 7 personas. Matches how ce-code-review shipped the same quality upgrade.
• Keep R9–R11 confidence gates in synthesis (synthesis-and-presentation.md step 3.2), not in personas. Personas keep their existing HIGH/MODERATE/<0.50 calibration.
• No diff passed in multi-round primer (R28). Fixed findings self-suppress (evidence gone); regressions surface as normal findings; rejected findings use pattern-match suppression. The diff would add prompt weight without changing what the agent can detect.
• Enum expansion values go on the knowledge track, not the bug track. All four new values (architecture_pattern, design_pattern, tooling_decision, convention) are knowledge-track per the two-track schema in schema.yaml:12-31.
• Update duplicate schema files in both ce-compound and ce-compound-refresh in the same commit. They are intentional duplicates; divergence is a known pitfall.
• Model tier/confidence/deferral as an explicit state machine (per git-workflow-skills-need-explicit-state-machines learning). See High-Level Technical Design for the state diagram.

Open Questions

Resolved During Planning

• Beta fork vs phased ship? Phased ship without beta. The overhaul is large but cleanly phaseable; each phase is independently testable; callers stay compatible via the preserved headless envelope contract (R27).
• Dispatch learnings-researcher from ce-doc-review? No. Dropped from scope (R31–R35 removed). The agent is ce-plan-owned; users who want institutional memory should inv