--- status: graduated --- # Solution Design: The Ask-Claude Document-Edit Flow (#42 · #47 · #46) | | | | --- | --- | | **Author(s)** | Ben Stull (with Claude) | | **Reviewers / approvers** | Ben Stull | | **Status** | `draft` | | **Version** | v0.1.0 | | **Source artifacts** | Features `benstull/vscode-cowriting-plugin#42` (Ask Claude to Edit Document, `type/feature`, `priority/P2`) · `#47` (block-granularity proposals, `type/feature`, `priority/P1`) · `#46` (accept-all, `type/feature`, `priority/P2`) · Epic `#1` (closed) · Capture sessions `vscode-cowriting-plugin-0035` (#42), `0040` (#47), `0039` (#46) · Brainstorming session `vscode-cowriting-plugin-0041` · Builds on (all shipped): F4 `#12` (propose/accept seam), F10 `#29` (interactive review preview), F11 `#43` (preview toolbar + `editDocument`/`runEditAndPropose`) · Parent specs (graduated): `coauthoring-propose-accept.md`, `coauthoring-attribution.md`, `coauthoring-interactive-review.md`, `coauthoring-rendered-preview.md` · F11 design currently lives in code + issue draft `issues/preview-toolbar-interaction-surface.md` (un-graduated — see §9) · Lineage: `ben.stull/rfc-app#48` | **Change log** | Date | Version | Change | By | | --- | --- | --- | --- | | 2026-06-12 | v0.1.0 | Initial draft — brainstorming session 0041. One combined design for the document-edit cluster, sequencing #42 → #47 → #46. Two forks locked with the operator: per-block proposals **preserve unchanged-span attribution** (block = decision unit, word = attribution unit); the cluster ships as **one** Solution Design. | Ben Stull + Claude | --- ## 1. Business Context ### 1.1 Executive Summary The plugin can already ask Claude to edit a whole document (F11 shipped `cowriting.editDocument` → `runEditAndPropose({kind:"document"})`), but the flow around that capability is rough on three sides, each captured as its own feature: - **You can't easily reach it** (#42). "Ask Claude to Edit" only appears in the editor body **when text is selected**. Right-clicking the body with *no* selection, or right-clicking the editor **tab**, offers nothing — two natural "do something with this document" gestures hit a dead end. - **What comes back is unreviewable** (#47, **P1**). A whole-document rewrite is diffed at **word** granularity (`diffToHunks`, INV-37): a light copy-edit pass explodes into dozens of tiny blue ✓/✗ blocks, forcing the reviewer to adjudicate word-fragments out of the sentence they live in. - **Taking the result is tedious** (#46). Accepting Claude's edits is **one proposal at a time**; a document a writer wants wholesale still demands a click per proposal. This design treats the three as **one flow** — **reach → review → accept** — and ships them in that order. **#42** makes the document edit reachable from the obvious gestures; **#47** cuts the rewrite into **one proposal per changed block** (paragraph / header / bullet / fence) so the reviewer decides in the unit they think in; **#46** adds a single **Accept all** gesture. The whole flow is built on the existing F4 propose/accept seam and the F10/F11 preview — **no new edit path, no new accept mechanism, no new persisted model.** ### 1.2 Background The inner loop shipped F2–F5 (threads · attribution · propose/accept · cross-rung). F10 (`#29`) collapsed the review surfaces into one: a **clean editor** + the **rendered markdown preview** as the single annotated review surface, with ✓/✗ acting only on pending F4 proposals (INV-32..34). F11 (`#43`) made the preview's **toolbar the primary interaction surface** — a **Pin baseline** button and an **adaptive Ask-Claude** button — and, as part of that, added the host-side **`cowriting.editDocument`** command and the **`runEditAndPropose`** path that diffs a whole-document rewrite into per-hunk F4 proposals (INV-35 sealed-webview intent, INV-36 `data-src` block→source mapping, INV-37 word-level per-hunk granularity). So the *capability* exists; this cluster is about the **experience around it**. Three captures landed it: - **0035 → #42**: "Add 'Ask Claude to Edit Document' on right-click with no selection; same Edit-Selection/Edit-Document on the tab." - **0040 → #47**: "A single change should be a paragraph (or header, or bulletpoint), not individual words. It's too much to review." - **0039 → #46**: "We need a way to accept all of Claude's edits." The captures themselves flagged that these "form an edit-flow cluster — brainstorm / sequence together," which this session does. ### 1.3 Business Actors / Roles - **Coauthor (human)** — the writer/engineer; the sole user of every gesture here (right-click to ask, ✓/✗ to adjudicate, Accept-all to commit). - **Coauthor (machine)** — Claude via `@cline/sdk`; produces the document rewrite that becomes block-level proposals; its accepted blocks land Claude-attributed (word-precise — §6, INV-40). ### 1.4 Problem Statement How do we make "ask Claude to revise this whole document, look at what it did, and take the parts I want" a **fluid, reviewable, low-friction** loop — when today it is **hard to invoke, exploded into word-fragments, and accepted one click at a time** — **without** forking a second edit path, a second accept mechanism, or a new persisted artifact? ### 1.5 Pain Points | # | Pain | Felt by | Today | | --- | --- | --- | --- | | P-1 | No whole-document ask from the body (no selection) or the tab | Mouse-first / tab-oriented writers | Dead-end gestures | | P-2 | A document edit fans out into many word-level proposals | Anyone reviewing a document edit (worse the lighter the edit) | "Too much to review" (#47, P1) | | P-3 | Accepting many proposals is one click each | Writers who want Claude's whole pass | Manual sweep of ✓ | | P-4 | Block-level accept could lose attribution fidelity inside a block | The product's F3 attribution value | (a design risk this spec resolves — INV-40) | ### 1.6 Targeted Business Outcomes - A **consistent "Ask Claude to Edit"** entry point — selection-scoped with a selection, whole-document without — from both the body and the tab. - A document edit produces a **small number of in-context, block-sized** decisions instead of a flood of word-fragments. - **"Take Claude's whole pass"** is a **single gesture**. - Attribution stays **word-precise** even though the decision unit is the block. ### 1.7 Scope (business) **In scope:** the three features as one sequenced flow — entry-point wiring (#42); document-edit proposal granularity word→block (#47); bulk-accept over the current document (#46). Each remains its own implementation increment / PR. **Out of scope / non-goals:** - **Selection edits are unchanged** — a selection edit is already a single proposal; #47 touches only the document path, #42 leaves selection behavior intact, #46 reuses the same seam. - **No Explorer context-menu entry** for Ask-Claude (#42 is tab + body only, per the capture; the review-panel Explorer entry shipped separately as #41). - **No "reject all"** (#46 is accept-only; a sibling ask if wanted). - **No cross-document / workspace-wide accept-all** — current document only. - **No new proposal-granularity *setting*** — block is the chosen unit, not a toggle. - **No change to the inline word-level ``/`` rendering** inside a block — the reviewer still sees exactly what changed; only the *decision unit* and the *attribution reconciliation* change. ### 1.8 Assumptions · Constraints · Dependencies - **F11 already shipped the document-edit path** (`editDocument`, `askClaude`, `runEditAndPropose`, `diffToHunks`). This is the strongest constraint: #42 is mostly **menu wiring** (the command exists); #47 **replaces the diff inside `runEditAndPropose`'s document branch**; #46 **loops the existing `acceptById`**. The cluster adds almost no new surface. - **The block model already exists** — `splitBlocks` / `splitBlocksWithRanges` / `diffBlocks` (`BlockOp`: unchanged / added / removed / changed+atomic; fences atomic per INV-23). #47 **reuses this**, not a second notion of "block." - **The F4 accept seam is the only mutation path** — `ProposalController.accept` → `AttributionController.applyAgentEdit` (`WorkspaceEdit`); the sealed webview posts **intent** only (INV-8/21/35). - **No new persisted artifact** (INV-20) — proposals live in the F4 sidecar; this cluster adds at most one transient field on the proposal (granularity marker — §6.3) and transient webview messages. - VS Code context menus render a command's own `title`; the tab menu picks one of two commands by a `when` clause on selection state (no per-menu relabel of one command). ### 1.9 Business Use Cases - **BUC-1 (reach)** — A writer right-clicks the document (body, no selection) or the tab and asks Claude to edit the whole document. - **BUC-2 (review)** — The writer reads Claude's pass as block-sized proposals and accepts/rejects each. - **BUC-3 (accept)** — The writer, happy with the pass, accepts all pending proposals in one gesture. --- ## 2. Solution Proposal **One flow, three increments, all on existing seams.** ```mermaid flowchart LR subgraph reach["#42 — REACH"] body["right-click body / tab\n(selection-aware)"] --> cmd["editSelection /\neditDocument"] end subgraph review["#47 — REVIEW"] cmd --> rep["runEditAndPropose\n(document branch)"] rep -- "diffToBlockHunks\n(per changed block)" --> props["F4 proposals\n(one per block)"] end subgraph accept["#46 — ACCEPT"] props --> one["✓/✗ per block"] props --> all["Accept all\n(toolbar intent)"] end one --> seam["F4 acceptById →\napplyAgentEdit"] all --> seam seam -- "block proposals: word-precise\nintra-block attribution (INV-40)" --> doc[(document)] ``` The defining idea of the cluster is in **#47's accept**: a document edit's proposals are cut at **block** granularity (the unit a human reviews), but each accept reconciles attribution at **word** granularity (the unit F3 records). The block is the **decision** unit; the word is the **attribution** unit. This is what lets us coarsen the review without coarsening the attribution — and it reuses the *exact* word-level machinery (`diffToHunks`) that INV-37 used, now repurposed as the intra-block sub-diff at accept time rather than the proposal cut. --- ## 3. Product Personas - **PP-1 (the coauthoring writer)** — edits a markdown document with Claude; wants to invoke a whole-document pass quickly, review it at paragraph altitude, and take it wholesale or selectively. --- ## 4. Product Use Cases | PUC | As PP-1 I… | Feature | Acceptance | | --- | --- | --- | --- | | PUC-1 | right-click the body with **no selection** → **Ask Claude to Edit Document** | #42 | whole-document edit → block proposals in the preview | | PUC-2 | right-click the body **with a selection** → **Ask Claude to Edit Selection** (unchanged) | #42 | one proposal over the selection (existing behavior) | | PUC-3 | right-click the **tab** → Edit Selection (if selection) / Edit Document (if not) | #42 | same behavior as the body equivalents, against that doc | | PUC-4 | see Claude's document edit as **one proposal per changed block** | #47 | M changed blocks → M proposals; unchanged blocks → none; fences atomic | | PUC-5 | accept a block proposal and have **only Claude's actual changes** attributed to Claude | #47 | unchanged words inside the accepted block keep their prior author (INV-40) | | PUC-6 | press **Accept all** to take every pending proposal at once | #46 | all anchored proposals applied; orphans skipped + reported | --- ## 5. UX Layout - **#42 entry points.** Two existing commands, surfaced in two more menus: - **Editor body** (`editor/context`): **Ask Claude to Edit Selection** when `editorHasSelection`, **Ask Claude to Edit Document** when not. - **Editor tab** (`editor/title/context`): the same pair, gated the same way, targeting the tab's document. - Both entries appear **only for markdown / authorable** docs (mirroring `editSelection`'s `when`: `resourceScheme == file || untitled` + `editorLangId == markdown`). - **#47 review.** The preview is unchanged in *look* — the reviewer still sees word-level ``/`` inside each block. What changes: each **changed block** is **one `cw-proposal` block** carrying one `data-proposal-id` and one ✓/✗ pair, instead of several. A changed code/mermaid fence is one atomic proposal (INV-23). - **#46 accept-all.** An **Accept all** button in the F11 preview **toolbar**, shown when the document has **≥ 2 pending proposals**. Pressing it posts the `acceptAll` intent; on completion the host reports applied-vs-skipped (status message / toast). No confirmation dialog — VS Code undo restores (consistent with single accept). ``` ┌─ Review: my-doc.md ──────────────────────────────┐ │ [ Pin baseline ] [ Ask Claude ▾ ] [ Accept all ]│ ← Accept all visible only when ≥2 pending ├───────────────────────────────────────────────────┤ │ ## Heading │ │ ┌───────────────────────────── proposal ───────┐ │ │ │ The ~~quick brown~~ swift fox … ✓ ✗ │ │ ← one block, word-level ins/del inside │ └───────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────┘ ``` --- ## 6. Technical Design ### 6.1 Invariants Parent invariants **INV-1..INV-37 carry over except where #47 supersedes INV-37**. This cluster adds: - **INV-38 (consistent, selection-aware Ask-Claude entry points)** — "Ask Claude to Edit" is reachable from the editor **body** and the editor **tab**, **selection-scoped when there is a selection** (`cowriting.editSelection`), **whole-document when there is not** (`cowriting.editDocument`). Both menus are gated to **markdown / authorable** docs. Both scopes route through the **single** `runEditAndPropose` path — no divergent edit code (#42). - **INV-39 (document edits propose per changed block — supersedes INV-37)** — a whole-document rewrite is cut into **one F4 proposal per changed block**, where a block is the unit `splitBlocks` already recognizes (prose paragraph / header / bullet; code & mermaid fences **atomic**, INV-23). **Unchanged blocks produce no proposal.** A block proposal's anchor spans the **whole** source block and its replacement is Claude's **whole** version of that block. This **replaces** INV-37's per-hunk word-level granularity **for document edits** (selection edits are unaffected) (#47). - **INV-40 (block decision, word-precise attribution)** — accepting a block proposal applies Claude's whole block but attributes **only the runs Claude actually changed** to Claude; **unchanged spans within the block keep their prior authorship**. Mechanism: an intra-block **word** sub-diff at accept time (reusing `diffToHunks`) drives one `applyAgentEdit` per changed run. The **block is the decision unit; the word is the attribution unit** (#47). - **INV-41 (block-insertion anchoring)** — a newly **inserted** block (one Claude added) is anchored to an adjacent block boundary so its proposal **resolves and is acceptable** — the block-level analogue of `anchorInsertion`; **no unresolvable zero-width block proposal** (#47). - **INV-42 (accept-all = batched F4 seam; current doc; orphan-skip)** — `cowriting.acceptAllProposals` applies **every pending proposal on the current document** through the existing `acceptById` seam, in a **re-anchor-safe order**, **skipping (never force-applying)** proposals that can't anchor, and **reports applied-vs-skipped**. It is a **batched application of the existing accept path**, not a new mechanism; the webview button posts **intent** (INV-35). Per-proposal ✓/✗ is unchanged (#46). **Supersession (explicit):** **INV-39 reverses INV-37** (document rewrite → per *hunk*/word) in favour of per *block*. INV-37's word-level engine (`diffToHunks`) is **not removed** — it is **repurposed** as the intra-block sub-diff that realizes INV-40's word-precise attribution. The F11 spec carrying INV-37 is un-graduated (§9); this spec is the canonical home of the superseding decision. ### 6.2 High-level architecture All three increments are localized to four already-existing files; no new module is required (one new pure function + one new command + menu JSON). ```mermaid flowchart TD pkg["package.json\n(menus: editor/context + editor/title/context)"] -. "#42 wiring" .-> cmds cmds["editSelection / editDocument\n(existing commands)"] --> rep["runEditAndPropose\n(trackChangesPreview.ts)"] rep -- "selection branch (unchanged)" --> single["one single-range proposal"] rep -- "document branch (#47)" --> dbh["diffToBlockHunks\n(trackChangesModel.ts — NEW, pure)"] dbh --> blockprops["one proposal per changed block\n(granularity: 'block')"] single & blockprops --> pc["ProposalController\n(proposalController.ts)"] pc -- "accept (block) → intra-block sub-diff (#47, INV-40)" --> attr["AttributionController.applyAgentEdit\n(per changed run)"] pc -- "acceptAll (#46, INV-42)" --> pc tb["preview toolbar\nAccept all button"] -- "{type:'acceptAll'} intent (INV-35)" --> pc ``` - **`package.json`** (#42) — add `editSelection` + `editDocument` to `editor/context` and `editor/title/context`, each with a selection-state `when` clause; titles "Ask Claude to Edit Selection" / "Ask Claude to Edit Document". - **`trackChangesModel.ts`** (#47, pure / vscode-free) — add **`diffToBlockHunks(currentText, rewrittenText): EditHunk[]`**: split both sides into the existing block units, diff blocks (reusing `diffBlocks`/`diffArrays` keying), and emit **one `EditHunk` per changed-or-added block** spanning the whole block's source range → its rewrite text; fences atomic; inserted blocks anchored (INV-41). Returns the same `EditHunk[]` shape `diffToHunks` does, so the proposal-minting loop is unchanged. **`diffToHunks` stays** as the intra-block sub-diff helper for INV-40. - **`trackChangesPreview.ts`** (#42/#47) — `runEditAndPropose`'s **document branch** calls `diffToBlockHunks` instead of `diffToHunks`, and tags each minted proposal `granularity: "block"`; `editDocument` resolves the **tab's** document (URI arg) when invoked from `editor/title/context`, not only `activeTextEditor`. Adds the `acceptAll` inbound-message case (#46) → `proposals.acceptAllProposals`. - **`proposalController.ts`** (#47/#46): - `accept` (#47): when `proposal.granularity === "block"`, instead of one whole-block `applyAgentEdit`, compute the intra-block word sub-diff (`diffToHunks(resolvedBlockText, proposal.replacement)`) and apply **one `applyAgentEdit` per changed run** (Claude-attributed), unchanged runs left in place — one undo-grouped edit. Non-block proposals keep the existing single `applyAgentEdit`. - `acceptAllProposals(document)` (#46): gather pending proposals, apply via `acceptById` in **descending document order** (last anchor first, so earlier anchors' offsets stay valid), skip orphans (suppressing per-item warnings), and return `{ applied, skipped }` for the controller to report. ### 6.3 Data model & ownership **No new persisted artifact** (INV-20). The only model change is **one optional field** on the F4 `Proposal`: ```ts // F4 sidecar Proposal — additive, optional, defaulted (back-compat): interface Proposal { // …existing fields… granularity?: "block" | "single"; // "block" ⇒ accept reconciles attribution per word (INV-40) } ``` - A document-edit proposal is minted with `granularity: "block"`; selection proposals are `"single"` (or absent → treated as single). A missing field on an older sidecar reads as `"single"` — existing proposals accept exactly as before. - New transient webview message (host ⇄ webview), extending the F11 toolbar intents: ```ts // webview → host (intent only — INV-35) type ToolbarMsg = | /* …existing: setMode | accept | reject | pinBaseline | askClaude… */ | { type: "acceptAll" }; ``` Baseline owned by F6; proposals by F4 (sidecar); attribution by F3. This cluster adds no new ownership. ### 6.4 Interfaces & contracts - **`trackChangesModel`** (vscode-free): `diffToBlockHunks(currentText: string, rewrittenText: string): EditHunk[]` — deterministic; one hunk per changed/added block over the existing block units; fences atomic; inserted blocks anchored (INV-41). Same `EditHunk` shape as `diffToHunks`. `diffToHunks` is **retained** (intra-block sub-diff for INV-40). - **`ProposalController`**: `acceptAllProposals(document): Promise<{ applied: number; skipped: number }>` — batched accept over the document's pending set via the existing `acceptById` seam, re-anchor-safe order, orphan-skip (INV-42). The private `accept` gains the block-aware attribution branch (INV-40) keyed off `proposal.granularity`. - **Commands**: `cowriting.editDocument` (existing — extended to resolve a tab URI arg); new `cowriting.acceptAllProposals` (active doc; reachable outside the webview). ### 6.5 Per–Product-Use-Case design - **PUC-1/2/3 (#42)** — pure `package.json` menu wiring + the `editDocument` tab URI resolution. `runEditAndPropose` is reached unchanged; the only code touch is resolving the right document for the tab gesture (mirroring #41's clicked-doc resolution). - **PUC-4 (#47 cut)** — `diffToBlockHunks` replaces `diffToHunks` in the document branch. For each `BlockOp` that is `changed` or `added`, emit one `EditHunk`: `changed` → `[block.start, block.end) → after-block text`; `added` → a zero-width range anchored to the adjacent block boundary (INV-41) with the new block text + a separating newline as needed; `removed` → a hunk that deletes the block; `unchanged` → nothing. Fences (`atomic`) emit one whole-fence hunk (never word-refined). - **PUC-5 (#47 attribution, INV-40)** — at accept of a `block` proposal: re-resolve the anchor → the current block text; `diffToHunks(currentBlockText, replacement)` → the word-level changed runs *within* the block; apply each run's replacement via `applyAgentEdit` (Claude-attributed) in one undo-grouped `WorkspaceEdit`, leaving unchanged runs untouched so their prior attribution stands. Net buffer text equals the whole-block replacement; net attribution is word-precise. - **PUC-6 (#46)** — `acceptAllProposals`: snapshot the pending list, sort descending by resolved anchor start, `acceptById` each (block proposals take the INV-40 path automatically), tally applied vs. skipped-orphan, report once. ### 6.6 Non-functional requirements & cross-cutting concerns - **Determinism / testability** — `diffToBlockHunks` is pure and vscode-free (unit-tested like `diffToHunks`/`diffBlocks`). The INV-40 attribution reconciliation is exercised through the controller with a fake document. - **Security** — unchanged: the webview stays sealed; **Accept all** posts intent; the host validates and performs every mutation (INV-8/21/35). No LLM/secret surface enters the sandbox. - **Performance** — block diffing is cheaper than the prior word fan-out (fewer proposals minted/rendered). Accept-all is O(pending) seam calls; large documents bounded by proposal count, not document size. - **Reversibility** — accept-all is one undo-restorable step-set; block accept is one undo-grouped edit. No destructive irreversibility. ### 6.7 Key decisions & alternatives considered | Decision | Chosen | Alternative (rejected) | | --- | --- | --- | | Cluster artifact | **One combined Solution Design**, three increments sequenced #42→#47→#46 (§3.3 — one design absorbs the roadmap) | Three separate specs — more duplication of the shared F11 edit path + F4 seam | | #47 block model | **Reuse `splitBlocks`/`diffBlocks`** | Invent a second "block" notion — divergence risk (capture warned against it) | | #47 attribution of unchanged words in an accepted block | **Preserve unchanged spans** — block decision, word-precise attribution (INV-40), via intra-block `diffToHunks` sub-diff at accept | **Whole block → Claude** — simpler (one seam call) but loses F3 fidelity inside the block; operator chose fidelity | | #47 vs INV-37 | **Supersede** INV-37 for document edits; **repurpose** `diffToHunks` as the intra-block engine | Keep word-level proposals + a separate "group view" — two models, more surface | | #46 apply-order | **Descending document order** through `acceptById` (each accept re-resolves the fingerprint, INV-11) | Re-resolve-then-rescan after every accept — more work for the same result | | #46 confirmation | **None** (undo restores) | A confirm dialog — friction the single-accept path doesn't have | | #46 scope | **Current document only** | Workspace-wide — capture non-goal | | #42 surfaces | **Body + tab only**, selection-aware | Add Explorer entry — capture non-goal (#41 covers Explorer for the review panel) | ### 6.8 Testing strategy - **Unit (vitest, pure)** — `diffToBlockHunks`: N words across M blocks → **M** hunks (one per changed block, spanning the block); unchanged block → none; changed fence → **one atomic** hunk; inserted block → an anchored, resolvable hunk (INV-41); each hunk's `[start,end)` lands on real block boundaries in `currentText`. - **Unit (controller)** — INV-40: accepting a block proposal whose replacement changes 2 of 6 words attributes **only those 2 runs** to Claude (the other 4 keep prior author); orphaned block proposal is flagged, not force-applied. - **Host E2E (Playwright)** — - #42: body no-selection shows **Edit Document**; body selection shows **Edit Selection**; tab shows the right one per selection state; each produces proposal(s). - #47: a document edit changing words across M blocks yields **M proposals**, each spanning its block; unchanged block → none; changed fence → one atomic proposal; an inserted block accepts cleanly. - #46: with N pending proposals, **Accept all** applies all N (text replaced, Claude-attributed, proposals cleared); an orphaned proposal in the set is skipped and **reported**, not mangled; the button is hidden with < 2 pending. - **Manual smoke** — extend `docs/MANUAL-SMOKE-F11.md` (or a new `MANUAL-SMOKE-F12.md`) covering the three gestures end-to-end. ### 6.9 Failure modes, rollback & flags - **Orphaned proposal** (target text changed / missing) — single accept already warns + flags (never applied by guess); accept-all **skips** it and includes it in the applied-vs-skipped report (INV-42). Reject-or-undo remains the recovery. - **Inserted block fails to anchor** — INV-41's adjacent-boundary anchoring makes this resolvable; if the boundary block itself later changes, the proposal orphans and is handled as above (never silently dropped). - **Back-compat** — the additive `granularity` field defaults to `"single"`; pre-existing sidecars/proposals accept unchanged. No migration. - **No feature flags** — each increment ships green through the pipeline; this is a VS Code extension (no flotilla deploy stage). --- ## 7. Delivery Plan ### 7.1 Approach / strategy Ship the flow **reach → review → accept** as three independent planning-and-executing increments, each its own PR, in sequence. They are **code-independent** (different files / functions), so the order is chosen for **user-visible value compounding**, not technical dependency — each increment is usable on its own. > **WSJF note (transparent):** **#47 carries the P1 value** ("too much to review" > is the sharpest pain); #42 and #46 are P2. The operator set the goal "starting > with #42," and #42 is the smallest, lowest-risk increment (the command already > exists — it's menu wiring), so leading with it completes the entry-point story > first. Because the three are code-independent, **#47 and #42 could swap** with no > rework if the P1 review pain should land first — a one-line resequencing. ### 7.2 Slicing plan - **SLICE-1 — #42 (reach).** `package.json` menus (`editor/context` + `editor/title/context`, selection-aware, markdown-gated); `editDocument` resolves the tab's document; titles. **+ E2E** (body/tab × selection state → right item → proposal). Smallest; no model change. (INV-38.) - **SLICE-2 — #47 (review).** `diffToBlockHunks` (pure, + unit tests); document branch of `runEditAndPropose` switches to it and tags `granularity:"block"`; block-aware accept in `ProposalController` (intra-block sub-diff, INV-40); block-insertion anchoring (INV-41). **Supersede INV-37 → INV-39** in the spec/ invariant set. **+ unit + E2E.** The substantive increment. (INV-39/40/41.) - **SLICE-3 — #46 (accept).** `acceptAllProposals` (controller, re-anchor-safe order, orphan-skip + report); `cowriting.acceptAllProposals` command; preview toolbar **Accept all** button + `{type:"acceptAll"}` intent (shown ≥2 pending). **+ E2E.** (INV-42.) ### 7.3 Rollout / launch plan No deploy pipeline (VS Code extension — no flotilla / PPE / prod stages; the §9 pipeline's deploy stages don't apply). Each slice merges to `main` green (unit + host E2E). "Done" = merged with tests green; there is no prod-promotion gate for an extension increment. ### 7.4 Risks & mitigations | Risk | Mitigation | | --- | --- | | INV-40 intra-block multi-edit accept skews offsets mid-apply | Apply changed runs **last-position-first** within the block, one undo-grouped `WorkspaceEdit`; unit-test the 2-of-6-words case | | Block taxonomy edge cases (lists w/o blank lines, tables, blockquotes, nested) | **Reuse `splitBlocks` exactly** — whatever it already treats as one block *is* one proposal; document the taxonomy = the splitter's, no second notion | | Inserted-block anchor collides / can't resolve | INV-41 anchors to an adjacent **unchanged** block boundary; orphan-handling is the backstop (never force-applied) | | Accept-all on a large pending set partially applies then an orphan appears | Each `acceptById` is independent + re-resolves (INV-11); skipped orphans reported; undo restores the whole step-set | | F11 spec un-graduated → INV-35/36/37 only in code | This spec restates the load-bearing F11 invariants it depends on; §9 logs the graduation gap as a follow-up | --- ## 8. Traceability matrix | Requirement | PUC | Invariant / §6 | Slice | Feature | | --- | --- | --- | --- | --- | | Ask-Claude reachable body (no-sel) + tab, selection-aware | PUC-1/2/3 | INV-38, §6.5 | SLICE-1 | #42 | | Selection edit unchanged | PUC-2 | INV-38 (single path) | SLICE-1 | #42 | | Document edit → one proposal per changed block | PUC-4 | INV-39, §6.5 (`diffToBlockHunks`) | SLICE-2 | #47 | | Unchanged block → no proposal; fence atomic | PUC-4 | INV-39, INV-23 | SLICE-2 | #47 | | Accepted block attributes only changed words to Claude | PUC-5 | INV-40, §6.5 | SLICE-2 | #47 | | Inserted block anchors + accepts | PUC-4 | INV-41 | SLICE-2 | #47 | | Accept-all over current doc, orphan-skip + report | PUC-6 | INV-42, §6.5 | SLICE-3 | #46 | | All mutation via the F4 seam; webview intent-only | PUC-4/5/6 | INV-35, §6.6 | SLICE-2/3 | #47/#46 | --- ## 9. Open Questions & Decisions log **Decided this session (operator):** - **D-1** — #47 accepts **preserve unchanged-span attribution** (block = decision unit, word = attribution unit; INV-40). *Not* whole-block→Claude. - **D-2** — the cluster ships as **one** combined Solution Design (this doc), three sequenced increments. - **D-3 (driver call, low-confidence — for finalize review)** — sequence **#42 → #47 → #46** per the goal's "starting with #42," despite #47 carrying the P1 value. The three are code-independent so the order is reversible (§7.1). - **D-4 (driver call)** — block taxonomy = **exactly `splitBlocks`'s** units (no second notion of "block"); list/table/blockquote/nested behavior is whatever the splitter already does. - **D-5 (driver call)** — accept-all needs **no confirmation** (undo restores); button shown at **≥ 2** pending. **Open / deferred:** - **OQ-1** — Should **selection** edits *also* preserve-unchanged-span attribution for consistency with INV-40? Out of #47's captured scope (selection edits explicitly unchanged); a future consistency pass could unify them. **Not in this cluster.** - **OQ-2 (spec-hygiene, not blocking)** — the **F11 (#43) Solution Design is un-graduated** — INV-35/36/37 live only in code comments + the issue draft `issues/preview-toolbar-interaction-surface.md`, not in `specs/`. This spec restates the F11 invariants it depends on and supersedes INV-37 here, but the F11 design should be graduated to `specs/` for a clean invariant ledger. Captured for finalize as a follow-up. - **OQ-3** — Very large blocks: no special fallback is specified (block proposals are bounded by the block, and accept reconciles per word). Revisit only if a pathological single-giant-block document surfaces. --- ## 10. Glossary & References - **Block** — the unit `splitBlocks` recognizes: a prose paragraph, header, or bullet/list item; a code or mermaid fence (atomic, INV-23). The #47 decision unit. - **Block proposal** — an F4 proposal whose anchor spans a whole block and whose replacement is Claude's whole version of that block (`granularity: "block"`). - **Intra-block sub-diff** — the word-level `diffToHunks` run *inside* an accepted block to realize word-precise attribution (INV-40). - **`diffToHunks` / `diffToBlockHunks`** — word-level (legacy INV-37; now the intra-block engine) / block-level (INV-39, new) document-rewrite differs, both emitting `EditHunk[]`. - **References** — `coauthoring-propose-accept.md` (F4 seam, INV-9..13), `coauthoring-interactive-review.md` (F10 preview, INV-32..34), `coauthoring-attribution.md` (F3, `applyAgentEdit`/`spansFor`), `issues/preview-toolbar-interaction-surface.md` (F11, INV-35..37 — un-graduated), features `#42` / `#47` / `#46`, capture sessions `0035` / `0040` / `0039`, brainstorming session `0041`. Lineage `ben.stull/rfc-app#48`.