| name | diffing-plan-review |
| description | Submit an implementation plan to diffing for human approval and obey the verdict before writing code. Use for plan sign-off, architecture review, risky work, or any request to let the human comment on a plan before implementation. |
Review an implementation plan with diffing
Use diffing as a real implementation gate: submit clean markdown, wait for the human decision, and do not begin implementation until the plan is approved.
Start and submit
Prefer MCP when available:
review_session_status, then start_review_session only for mode: none. Reuse mode: web. Plan tools do not run against the native TUI or GitHub PR API, and MCP will not replace those user-owned sessions; ask the human to end the incompatible session before retrying.submit_plan with complete markdown body, title, and model/source when known.await_plan_review. Timeout is normal; retry while the user still wants you to wait.
CLI fallback:
diffing --web --no-open
diffing plan submit [<plan.md>|-] [--title T] [--source S] [--model M] [--id ID] [--save-source]
diffing plan submit [<plan.md>|-] --wait [--timeout N]
diffing plan await [--timeout N]
Keep temporary plan files in ~/.diffing/<repo>/plan-sources/ — never in the consumer project tree. Use --save-source / -S to copy the submitted body there. Prefer stdin for zero working-tree footprint. Always resubmit revisions with the original plan --id so history stays one conversation.
Useful reads:
diffing plan list [--json]
diffing plan show [<id>] [--json] [--version n]
diffing plan versions <id> [--json]
Minimize duplicate reads: await_plan_review already returns the reviewed plan and relevant comments. Use get_plan / plan show only to refresh the current plan, get_plan_versions / plan versions for lightweight history metadata, and get_plan_version / plan show --version only for a specific historical body. Do not fetch every historical body by default.
Use plan CLI/MCP/API operations instead of editing plans.json; the file-backed store, version snapshots, comment anchors, and plan-sources/<id>.md mirror are implementation-owned state under per-repository ~/.diffing/ storage.
MCP intentionally exposes reply and resolve for plan comments, but not edit/delete/reply-edit operations. When correcting a mis-posted plan thread and no native command exists, use the documented loopback /api/plans/:id/comments* endpoints; deletion is destructive and requires clear intent.
Obey the verdict
| Decision | Action |
|---|
approved | Implement the reviewed version; account for open inline comments. |
changes-requested | Do not implement. Reply to open threads, revise plan, resolve addressed threads, submit same planId, await again. |
rejected | Stop. Do not implement or extend the rejected approach. |
comment-only | Do not edit files or implement. Only answer questions / discuss. |
pending | Keep waiting or report no decision yet. |
MCP: reply_to_plan_comment, resolve_plan_comment, get_plan, get_plan_versions, get_plan_version.
CLI:
diffing plan reply <comment-id> --body "..." --model "<model-name>"
diffing plan resolve <comment-id>
diffing plan submit <revised-plan.md> --id <plan-id> --model "<model-name>"
Only address comments with status="open". Questions stay open after reply; resolve a change request only when the revised plan incorporates it.
Plan comments, ranges, and severity
Human comments on the plan appear in <plan-review> XML with:
line="N" or inclusive line="A-B" (multi-line selection)- optional
severity="blocking|nit|question|praise" (same triage as code review)
- optional section title and source/quote context
Treat blocking as must-fix before resubmit; nit as optional; question as needing a reply (usually leave open); praise as no change required. Missing severity = untriaged normal request.
Human UI notes (so agents set expectations)
The human reviews at /plan or /plan/<id>:
| Feature | Behavior |
|---|
| Source / Read / Split | m cycles modes; toolbar switches the same modes |
| Zen Read | z toggles full-width focus (switches to Read if needed); Esc exits zen when not editing |
| Live edit | e / pencil: edit current version markdown + title; autosave PUT (no version bump); Save as new version = POST same id; Esc opens Discard |
| Discard | Recent = this session; original = first enter for this version (survives exit/re-enter). Dual choice only when both apply |
| Comments map (right rail) | c toggles; lists open threads with L / Lstart–Lend labels |
| Inline comments | Source: gutter + / line selection; Read: text highlight → Add comment; multi-line ranges with optional severity (paused while live-editing) |
| Read mode threads | Comments render inline under the matching section (React-owned; survives mode switches) |
| Comment cards | Collapsible thread; collapsible source preview inside the card |
| Submit review | Verdict that unblocks plan await |
Plans may be versioned; comments are version-anchored when the human browses history. Human in-page edits use PUT (same version) unless they explicitly Save as new version.
