feat(ce-doc-review): autofix tiers, per-finding walk-through, multi-round memory

docs/solutions/adding-converter-target-providers.md

@@ -5,7 +5,7 @@ tags: [converter, target-provider, plugin-conversion, multi-platform, pattern]
 created: 2026-02-23
 severity: medium
 component: converter-cli
-problem_type: best_practice
+problem_type: architecture_pattern
 root_cause: architectural_pattern
 ---
 

docs/solutions/best-practices/codex-delegation-best-practices-2026-04-01.md

@@ -3,7 +3,7 @@ title: "Codex Delegation Best Practices"
 date: 2026-04-01
 category: best-practices
 module: "Codex delegation / skill design"
-problem_type: best_practice
+problem_type: convention
 component: tooling
 severity: medium
 applies_when:

docs/solutions/best-practices/conditional-visual-aids-in-generated-documents-2026-03-29.md

@@ -3,7 +3,7 @@ title: Conditional visual aids in generated documents and PR descriptions
 date: 2026-03-29
 category: best-practices
 module: compound-engineering plugin skills
-problem_type: best_practice
+problem_type: design_pattern
 component: documentation
 symptoms:
   - "Generated documents and PR descriptions lack visual aids that would improve comprehension of complex workflows and relationships"

docs/solutions/best-practices/prefer-python-over-bash-for-pipeline-scripts-2026-04-09.md

@@ -3,7 +3,7 @@ title: "Prefer Python over bash for multi-step pipeline scripts"
 date: 2026-04-09
 category: best-practices
 module: "skill scripting / ce-demo-reel"
-problem_type: best_practice
+problem_type: tooling_decision
 component: tooling
 severity: medium
 applies_when:

docs/solutions/codex-skill-prompt-entrypoints.md

@@ -5,7 +5,7 @@ tags: [codex, converter, skills, prompts, workflows, deprecation]
 created: 2026-03-15
 severity: medium
 component: codex-target
-problem_type: best_practice
+problem_type: convention
 root_cause: outdated_target_model
 ---
 

docs/solutions/skill-design/discoverability-check-for-documented-solutions-2026-03-30.md

@@ -3,7 +3,7 @@ title: Discoverability check for documented solutions in project instruction fil
 date: 2026-03-30
 category: skill-design
 module: compound-engineering
-problem_type: best_practice
+problem_type: convention
 component: tooling
 severity: medium
 applies_when:

docs/solutions/skill-design/git-workflow-skills-need-explicit-state-machines-2026-03-27.md

@@ -3,7 +3,7 @@ title: "Git workflow skills need explicit state machines for branch, push, and P
 category: skill-design
 date: 2026-03-27
 module: plugins/compound-engineering/skills/git-commit and git-commit-push-pr
-problem_type: best_practice
+problem_type: architecture_pattern
 component: tooling
 symptoms:
   - Detached HEAD could fall through to invalid push or PR paths

docs/solutions/skill-design/pass-paths-not-content-to-subagents-2026-03-26.md

@@ -1,6 +1,6 @@
 ---
 title: "Pass paths, not content, when dispatching sub-agents"
-problem_type: best_practice
+problem_type: design_pattern
 component: tooling
 root_cause: inadequate_documentation
 resolution_type: workflow_improvement

docs/solutions/skill-design/research-agent-pipeline-separation-2026-04-05.md

@@ -3,7 +3,7 @@ title: Research agent dispatch is intentionally separated across the skill pipel
 date: 2026-04-05
 category: skill-design
 module: compound-engineering
-problem_type: best_practice
+problem_type: architecture_pattern
 component: tooling
 severity: low
 applies_when:

docs/solutions/workflow/todo-status-lifecycle.md

@@ -13,7 +13,7 @@ related_components:
   - plugins/compound-engineering/skills/ce-review/
   - plugins/compound-engineering/skills/todo-triage/
   - plugins/compound-engineering/skills/todo-create/
-problem_type: correctness-gap
+problem_type: workflow_issue
 ---
 
 # Status-Gated Todo Resolution

plugins/compound-engineering/AGENTS.md

@@ -215,6 +215,10 @@ Beta skills use a `-beta` suffix and `disable-model-invocation: true` to prevent
 
 When modifying a skill that has a `-beta` counterpart (or vice versa), always check the other version and **state your sync decision explicitly** before committing — e.g., "Propagated to beta — shared test guidance" or "Not propagating — this is the experimental delegate mode beta exists to test." Syncing to both, stable-only, and beta-only are all valid outcomes. The goal is deliberate reasoning, not a default rule.
 
+## Documented Solutions
+
+`docs/solutions/` holds documented solutions to past problems — bugs, architecture patterns, design patterns, tooling decisions, conventions, workflow practices, and other institutional knowledge. Entries use YAML frontmatter with fields including `module`, `tags`, and `problem_type`. Knowledge-track `problem_type` values are `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention`, `workflow_issue`, `developer_experience`, `documentation_gap`, and `best_practice` (fallback). Bug-track values cover `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, and `logic_error`. Search this directory before designing new solutions so institutional memory compounds across changes.
+
 ## Documentation
 
 See `docs/solutions/plugin-versioning-requirements.md` for detailed versioning workflow.

plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml

@@ -23,12 +23,16 @@ tracks:
       - integration_issue
       - logic_error
   knowledge:
-    description: "Best practices, workflow improvements, patterns, and documentation"
+    description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
     problem_types:
       - best_practice
       - documentation_gap
       - workflow_issue
       - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
 
 # --- Fields required by BOTH tracks -----------------------------------------
 required_fields:
@@ -57,7 +61,11 @@ required_fields:
       - workflow_issue
       - best_practice
       - documentation_gap
-    description: "Primary category — determines track (bug vs knowledge)"
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+    description: "Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits."
 
   component:
     type: enum

plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md

@@ -16,7 +16,7 @@ The `problem_type` determines which **track** applies. Each track has different
 | Track | problem_types | Description |
 |-------|--------------|-------------|
 | **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
-| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention` | Practices, patterns, conventions, decisions, workflow improvements, and documentation. Prefer the narrowest applicable value; `best_practice` is the fallback. |
 
 ## Required Fields (both tracks)
 
@@ -73,6 +73,10 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
 - `workflow_issue` -> `docs/solutions/workflow-issues/`
 - `best_practice` -> `docs/solutions/best-practices/`
 - `documentation_gap` -> `docs/solutions/documentation-gaps/`
+- `architecture_pattern` -> `docs/solutions/architecture-patterns/`
+- `design_pattern` -> `docs/solutions/design-patterns/`
+- `tooling_decision` -> `docs/solutions/tooling-decisions/`
+- `convention` -> `docs/solutions/conventions/`
 
 ## Validation Rules
 

plugins/compound-engineering/skills/ce-compound/SKILL.md

@@ -410,10 +410,14 @@ Bug track:
 - logic-errors/
 
 Knowledge track:
-- best-practices/
+- architecture-patterns/ — architectural or structural patterns (agent/skill/pipeline/workflow shape decisions)
+- design-patterns/ — reusable non-architectural design approaches (content generation, interaction patterns, prompt shapes)
+- tooling-decisions/ — language, library, or tool choices with durable rationale
+- conventions/ — team-agreed way of doing something, captured so it survives turnover
 - workflow-issues/
 - developer-experience/
 - documentation-gaps/
+- best-practices/ — fallback only, use when no narrower knowledge-track value applies
 
 ## Common Mistakes to Avoid
 

plugins/compound-engineering/skills/ce-compound/references/schema.yaml

@@ -23,12 +23,16 @@ tracks:
       - integration_issue
       - logic_error
   knowledge:
-    description: "Best practices, workflow improvements, patterns, and documentation"
+    description: "Practices, patterns, conventions, decisions, workflow improvements, and documentation"
     problem_types:
       - best_practice
       - documentation_gap
       - workflow_issue
       - developer_experience
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
 
 # --- Fields required by BOTH tracks -----------------------------------------
 required_fields:
@@ -57,7 +61,11 @@ required_fields:
       - workflow_issue
       - best_practice
       - documentation_gap
-    description: "Primary category — determines track (bug vs knowledge)"
+      - architecture_pattern
+      - design_pattern
+      - tooling_decision
+      - convention
+    description: "Primary category — determines track (bug vs knowledge). Prefer the narrowest applicable value; best_practice is the fallback when no narrower knowledge-track value fits."
 
   component:
     type: enum

plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md

@@ -16,7 +16,7 @@ The `problem_type` determines which **track** applies. Each track has different
 | Track | problem_types | Description |
 |-------|--------------|-------------|
 | **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
-| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`, `architecture_pattern`, `design_pattern`, `tooling_decision`, `convention` | Practices, patterns, conventions, decisions, workflow improvements, and documentation. Prefer the narrowest applicable value; `best_practice` is the fallback. |
 
 ## Required Fields (both tracks)
 
@@ -73,6 +73,10 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
 - `workflow_issue` -> `docs/solutions/workflow-issues/`
 - `best_practice` -> `docs/solutions/best-practices/`
 - `documentation_gap` -> `docs/solutions/documentation-gaps/`
+- `architecture_pattern` -> `docs/solutions/architecture-patterns/`
+- `design_pattern` -> `docs/solutions/design-patterns/`
+- `tooling_decision` -> `docs/solutions/tooling-decisions/`
+- `convention` -> `docs/solutions/conventions/`
 
 ## Validation Rules
 

plugins/compound-engineering/skills/ce-doc-review/SKILL.md

@@ -6,28 +6,34 @@ argument-hint: "[mode:headless] [path/to/document.md]"
 
 # Document Review
 
-Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-fixes quality issues, and presents strategic questions for user decision.
+Review requirements or plan documents through multi-persona analysis. Dispatches specialized reviewer agents in parallel, auto-applies `safe_auto` fixes, and routes remaining findings through a four-option interaction (per-finding walk-through, LFG, Append-to-Open-Questions, Report-only) for user decision.
+
+## Interactive mode rules
+
+- **Pre-load the platform question tool before any question fires.** In Claude Code, `AskUserQuestion` is a deferred tool — its schema is not available at session start. At the start of Interactive-mode work (before the routing question, per-finding walk-through questions, bulk-preview Proceed/Cancel, and Phase 5 terminal question), call `ToolSearch` with query `select:AskUserQuestion` to load the schema. Load it once, eagerly, at the top of the Interactive flow — do not wait for the first question site. On Codex (`request_user_input`) and Gemini (`ask_user`) this step is not required; the tools are loaded by default.
+- **The numbered-list fallback only applies on confirmed load failure.** Presenting options as a numbered list and waiting for the user's reply is valid only when `ToolSearch` returns no match or the tool call explicitly fails. Rendering a question as narrative text because the tool feels inconvenient, because the model is in report-formatting mode, or because the instruction was buried in a long skill is a bug. A question that calls for a user decision must either fire the tool or fail loudly.
 
 ## Phase 0: Detect Mode
 
-Check the skill arguments for `mode:headless`. Arguments may contain a document path, `mode:headless`, or both. Tokens starting with `mode:` are flags, not file paths -- strip them from the arguments and use the remaining token (if any) as the document path for Phase 1.
+Check the skill arguments for `mode:headless`. Arguments may contain a document path, `mode:headless`, or both. Tokens starting with `mode:` are flags, not file paths — strip them from the arguments and use the remaining token (if any) as the document path for Phase 1.
 
 If `mode:headless` is present, set **headless mode** for the rest of the workflow.
 
-**Headless mode** changes the interaction model, not the classification boundaries. Document-review still applies the same judgment about what has one clear correct fix vs. what needs user judgment. The only difference is how non-auto findings are delivered:
-- `auto` fixes are applied silently (same as interactive)
-- `present` findings are returned as structured text for the caller to handle -- no AskUserQuestion prompts, no interactive approval
-- Phase 5 returns immediately with "Review complete" (no refine/complete question)
+**Headless mode** changes the interaction model, not the classification boundaries. ce-doc-review still applies the same judgment about which tier each finding belongs in. The only difference is how non-safe_auto findings are delivered:
+
+- `safe_auto` fixes are applied silently (same as interactive)
+- `gated_auto`, `manual`, and FYI findings are returned as structured text for the caller to handle — no AskUserQuestion prompts, no interactive routing
+- Phase 5 returns immediately with "Review complete" (no routing question, no terminal question)
 
 The caller receives findings with their original classifications intact and decides what to do with them.
 
 Callers invoke headless mode by including `mode:headless` in the skill arguments, e.g.:
+
 ```
 Skill("ce-doc-review", "mode:headless docs/plans/my-plan.md")
 ```
 
-
-If `mode:headless` is not present, the skill runs in its default interactive mode with no behavior change.
+If `mode:headless` is not present, the skill runs in its default interactive mode with the routing question, walk-through, and bulk-preview behaviors documented in `references/walkthrough.md` and `references/bulk-preview.md`.
 
 ## Phase 1: Get and Analyze Document
 
@@ -124,16 +130,54 @@ Dispatch all agents in **parallel** using the platform's task/agent tool (e.g.,
 | `{document_type}` | "requirements" or "plan" from Phase 1 classification |
 | `{document_path}` | Path to the document |
 | `{document_content}` | Full text of the document |
+| `{decision_primer}` | Cumulative prior-round decisions in the current session, or an empty `<prior-decisions>` block on round 1. See "Decision primer" below. |
+
+Pass each agent the **full document** — do not split into sections.
+
+### Decision primer
+
+On round 1 (no prior decisions), set `{decision_primer}` to:
+
+```
+<prior-decisions>
+Round 1 — no prior decisions.
+</prior-decisions>
+```
+
+On round 2+ (after one or more prior rounds in the current interactive session), accumulate prior-round decisions and render them as:
 
-Pass each agent the **full document** -- do not split into sections.
+```
+<prior-decisions>
+Round 1 — applied (N entries):
+- {section}: "{title}" ({reviewer}, {confidence})
+  Evidence: "{evidence_snippet}"
+
+Round 1 — rejected (M entries):
+- {section}: "{title}" — Skipped because {reason}
+  Evidence: "{evidence_snippet}"
+- {section}: "{title}" — Deferred to Open Questions because {reason or "no reason provided"}
+  Evidence: "{evidence_snippet}"
+
+Round 2 — applied (N entries):
+...
+</prior-decisions>
+```
+
+Each entry carries an `Evidence:` line because synthesis R29 (rejected-finding suppression) and R30 (fix-landed verification) both use an evidence-substring overlap check as part of their matching predicate — without the evidence snippet in the primer, the orchestrator cannot compute the `>50%` overlap test and has to fall back to fingerprint-only matching, which either re-surfaces rejected findings or suppresses too aggressively. The `{evidence_snippet}` is the first evidence quote from the finding, truncated to the first ~120 characters (preserving whole words at the boundary) and with internal quotes escaped. If a finding has multiple evidence entries, use the first one; the rest live in the run artifact and are not needed for the overlap check.
+
+Accumulate across all rounds in the current session. Skip and Defer actions both count as "rejected" for suppression purposes — both signal the user decided the finding wasn't worth actioning this round. Applied findings stay on the applied list so round-N+1 personas can verify fixes landed (see R30 in `references/synthesis-and-presentation.md`).
+
+Cross-session persistence is out of scope. A new invocation of ce-doc-review on the same document starts with a fresh round 1 and no carried primer, even if prior sessions deferred findings into the document's Open Questions section.
 
 **Error handling:** If an agent fails or times out, proceed with findings from agents that completed. Note the failed agent in the Coverage section. Do not block the entire review on a single agent failure.
 
 **Dispatch limit:** Even at maximum (7 agents), use parallel dispatch. These are document reviewers with bounded scope reading a single document -- parallel is safe and fast.
 
 ## Phases 3-5: Synthesis, Presentation, and Next Action
 
-After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, gate, dedup, promote, resolve contradictions, route by autofix class), auto-fix application, finding presentation, and next-action menu. Do not load this file before agent dispatch completes.
+After all dispatched agents return, read `references/synthesis-and-presentation.md` for the synthesis pipeline (validate, per-severity gate, dedup, cross-persona agreement boost, resolve contradictions, auto-promotion, route by three tiers with FYI subsection), `safe_auto` fix application, headless-envelope output, and the handoff to the routing question.
+
+For the four-option routing question and per-finding walk-through (interactive mode), read `references/walkthrough.md`. For the bulk-action preview used by LFG, Append-to-Open-Questions, and walk-through `LFG-the-rest`, read `references/bulk-preview.md`. Do not load these files before agent dispatch completes.
 
 ---