diffing-plan-review

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:

1. Call review_session_status. Plan tools require mode: web. If another mode is active, use diffing sessions --json to select a compatible web session, or start diffing --web --no-open as a concurrent session; do not end the TUI/PR review merely to submit a plan. Reconnect MCP after sessions use so the new connection discovers the selected web session.
2. Call start_review_session only for mode: none or to idempotently reuse/pin a matching web scope. It never creates a plan-specific session and never launches, stops, or replaces TUI/PR sessions.
3. submit_plan with complete markdown body, title, and model/source when known.
4. Async handoff (default): share the plan URL returned by submit_plan, tell the human to review, and end your turn. Do not call status or fetch the plan just to rediscover that URL. Call await_plan_review only when they are reviewing now or explicitly asked you to wait.
5. On await_plan_review timeout (disposition=park): park again — do not silent-loop. At most one extra await if they asked you to keep waiting. When they say a verdict is ready, call await_plan_review once (or get_plan / list_plans).

CLI fallback:

diffing sessions --json
diffing sessions use <web-session-id>       # reuse a compatible web session
# Or, when none matches:
diffing --web --no-open                     # starts a concurrent active session
diffing plan submit [<plan.md>|-] [--title T] [--source S] [--model M] [--id ID] [--save-source]
# default: prints URL and parks — do not add --wait unless sync
diffing plan submit [<plan.md>|-] --wait [--timeout N]   # sync only
diffing plan await [--timeout N]                         # sync / resume
# or: cat PLAN.md | diffing plan submit --model "..."

Keep temporary plan files in ~/.diffing/<repo>/plan-sources/ — never in the consumer project tree. Use --save-source (or -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]  # omit id for latest
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	Park (async) or sync-await once if asked; do not silent-loop on timeout.

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 facts (so agents set expectations)

• The human reviews at /plan or /plan/<id> and finishes with Submit review — the verdict that unblocks plan await.
• Humans comment inline on Source or Read with multi-line ranges and optional severity.
• Human live-edit autosaves the current version in place; only an explicit "Save as new version" bumps the version, and comments stay version-anchored.