ce-doc-review

CE Document Review

Review a Compound Engineering markdown or HTML plan/requirements document. Markdown artifacts may receive safe markdown-only fixes; HTML artifacts may receive only the DOM-safe mutations proven by the FN-7149 helper and otherwise remain report-only with no mutation.

Modes

• mode:headless <path>: run an automated advisory pass and return a concise review envelope. For markdown, apply only safe_auto markdown fixes; for HTML, attempt only the allowlisted DOM-safe helper operations and fall back to report-only (fixes_applied = 0) whenever safety cannot be proven.
• <path> without mode:headless: run the same review for an interactive caller. For markdown, include actionable findings clearly enough for the caller to decide what to apply; for HTML, present findings with DOM-safe mutation status and do not offer markdown apply-set or markdown Append-to-Open-Questions write-back options.

Review boundary

ce-brainstorm owns WHAT: product requirements, actors, flows, acceptance examples, and scope boundaries.

ce-plan owns HOW: technical decisions, implementation units, dependencies, risks, verification contract, and handoff posture.

ce-doc-review checks whether the document preserves that boundary and is usable by downstream ce-work, PR reviewers, and humans. Do not turn document review into code review; ce-code-review owns implementation diff review later in the pipeline.

Procedure

1. Resolve the target path from the arguments. Prefer an explicit path. If no path is provided, inspect docs/plans/ for the most recent markdown (.md) or HTML (.html) plan-like artifact and use that; if none exists, skip non-blockingly.
2. Classify the target type:
   • Markdown (.md): review with markdown-safe mutation enabled for safe_auto fixes only.
   • HTML (.html): review with DOM-safe mutation enabled only for the FN-7149/FN-7159 allowlist: append to an existing Open/Outstanding Questions list, provable stable-registry heading-depth repair, duplicate inter-block whitespace normalization, exact visible-prose typo text-node fixes, and malformed checklist repair to the canonical HTML checklist representation. Run the same document-quality and persona-lens checks, preserve classifications, and fall back to report-only with fixes_applied/applied_fixes_count set to 0 whenever the helper refuses. Do not run markdown safe_auto writes, gated_auto/manual apply-set edits, or Append-to-Open-Questions write-back that inserts markdown ##/### headings.
   • Any other type: skip non-blockingly and explain that only markdown and HTML CE plan/requirements artifacts are supported.
3. Read the document enough to evaluate structure and consistency. For long documents, scan headings first, then read the Goal Capsule/Product Contract/Plan/Implementation Units/Verification/Definition of Done sections as present. For HTML, use the rendered document text/semantic headings as review input; never rewrite tags with markdown text edits, inject markdown, or mutate outside the DOM-safe helper.
4. Check for:
   • Product scope drift: requirements or Product Contract rewritten without a clear preservation note.
   • HOW gaps: implementation units lacking files, dependencies, risks, or verification scenarios.
   • Coherence gaps: contradictory decisions, stale handoff instructions, duplicated or inconsistent artifact readiness metadata.
   • Feasibility gaps: sequencing that cannot work, missing prerequisite decisions, or verification that cannot prove the stated Definition of Done.
   • Hygiene that is safe to fix automatically in the target format: markdown-only broken heading levels, duplicate blank lines, malformed checklists, or typo-level wording for markdown; for HTML, only the DOM-safe helper operations may apply, including malformed-checklist repair when the helper can prove the canonical checklist form deterministically. Ambiguous or non-canonical checklist-like HTML that cannot be proven safe stays report-only.
5. In headless mode, apply only safe_auto fixes directly to markdown files. Do not apply changes that alter product scope, technical decisions, acceptance criteria, or verification obligations; report those as findings. In HTML mode, call the DOM-safe helper only for allowlisted operations; on any round-trip, anchor, protected-region, visible-text, checklist-equivalence, validation, unsupported-operation, or write failure, apply nothing and return the review envelope with fixes_applied = 0 and classifications intact.
6. If findings remain, classify each as:
   • proposed_fix: a safe but non-trivial improvement the user may accept.
   • decision: a scope/technical judgment that needs human or planner choice.
   • fyi: useful observation that does not need routing.
7. Interactive routing:
   • Markdown: the caller may choose whether to apply proposed fixes, route decisions, or append unresolved items to Open Questions.
   • HTML: skip markdown apply and markdown Append-to-Open-Questions choices entirely. Present findings with DOM-safe mutation status; checklist repair may write only the canonical HTML checklist representation after helper validation, and every unsupported or unsafe finding remains report-only with the HTML artifact unchanged.
8. End with a concise summary and exactly one trailing JSON object on the final line.

Output contract

Use this shape for the final line:

{"verdict":"APPROVE|APPROVE_WITH_NOTES|REVISE","fixes_applied":0,"proposed_fixes_count":0,"decisions_count":0,"fyi_count":0,"notes":"short summary"}

• APPROVE: no actionable issues remain.
• APPROVE_WITH_NOTES: non-blocking observations or report-only HTML findings; this is the normal result for optional workflow use.
• REVISE: only for severe document issues that make downstream work unsafe or impossible. In the Fusion built-in workflow this skill is advisory/non-blocking, but the verdict still helps humans see severity.

For HTML reviews, the JSON must still be emitted. When DOM-safe mutation is refused or unsupported, fixes_applied must be 0, and notes should mention that HTML fell back to report-only without autofix; successful DOM-safe helper fixes may increment fixes_applied only for the allowlisted operations, including canonical checklist repair.

Do not wrap the final JSON in markdown fences.