From 9f0d896ea9c34e3751b2b6d04d116cf021d0d774 Mon Sep 17 00:00:00 2001 From: BenStullsBets Date: Sun, 28 Jun 2026 08:07:00 -0700 Subject: [PATCH] =?UTF-8?q?spec(0062):=20staged=20delivery=20(=C2=A77.1)?= =?UTF-8?q?=20+=20companion=20feasibility=20spike=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §7.1 now records the 4 de-risking rungs (mockups → throwaway feasibility spike → vertical slice → full build), riskiest-API-assumption-first, so any forced design change lands on throwaway code. Adds coauthoring-feasibility- spike.md: 5 experiments (E1 editable proposals+Keep/Undo, E2 baseline router, E3 preview authorship, E4 comment loop, E5 discoverability) with PASS/FAIL criteria; closes open Q2/Q4/Q7 before any plan is written. Co-Authored-By: Claude Opus 4.8 (1M context) --- specs/coauthoring-feasibility-spike.md | 114 +++++++++++++++++++++++++ specs/coauthoring-native-surfaces.md | 35 ++++++-- 2 files changed, 142 insertions(+), 7 deletions(-) create mode 100644 specs/coauthoring-feasibility-spike.md diff --git a/specs/coauthoring-feasibility-spike.md b/specs/coauthoring-feasibility-spike.md new file mode 100644 index 0000000..ef9f72c --- /dev/null +++ b/specs/coauthoring-feasibility-spike.md @@ -0,0 +1,114 @@ +--- +status: draft +--- +# Feasibility Spike Plan — Coediting Markdown with a Machine (native surfaces) + +| | | +| --- | --- | +| **Companion to** | `coauthoring-native-surfaces.md` (Solution Design) — §7.1 rung 2 | +| **Type** | Throwaway discovery **prototype** (handbook §5.3) — code is disposable | +| **Goal** | Prove the API-dependent design assumptions on the **real** VS Code surfaces, cheaply, **before** the full build — so post-ship iteration is polish, not design | +| **Non-goal** | Production code, real Claude/SDK wiring (except E4), persistence durability, polish, breadth | +| **Status** | `draft` | + +--- + +## Why this exists + +Static mockups validated the *look* and *state coverage*; they prove **nothing** +about whether VS Code's native surfaces actually behave as the spec assumes. Twice +already, an unexamined assumption would have forced a redesign (the diff can't +recolor per author; the Comments API can't render in the preview). The remaining +high-risk assumptions can only be settled by **building on the real API**. This spike +does exactly that and nothing more: each experiment returns a **PASS / PASS-with- +fallback / FAIL**, and any FAIL becomes a spec delta folded back into +`coauthoring-native-surfaces.md` before a plan is written. + +## Shape & guardrails + +- **One throwaway VS Code extension** (`vscode-cowriting-prototype`), run in the + Extension Development Host. **Delete it when the spike ends** — none of this code + graduates. +- **The machine is stubbed** for E1–E3, E5 (a function returning canned `before/after` + edits) so we test *VS Code feasibility and feel*, not the SDK. E4 may use a minimal + real call only if cheap. +- **Time-box: ~2–3 focused days.** If an experiment can't be made to PASS or + PASS-with-fallback inside its slice, that is itself the finding — record it and move + on. +- **No persistence/durability work**, no anchoring ladder, no cross-rung format — those + are not API-risk; defer to the build. + +## Experiments (riskiest first) + +### E1 — Editable proposed side + Keep/Undo *(highest risk)* +- **Assumption (INV-12, Q2, Q7):** the machine's proposal can be reviewed in a + multi-diff / diff editor whose **proposed side is writable**, the writer can tweak it + before keeping, and **per-change Keep/Undo** works. +- **Build:** open a diff between a read-only baseline (`cowriting-baseline:` virtual + doc) and a **writable** proposal doc (untitled/in-memory) seeded with a canned edit; + attach Keep/Reject actions (try the multi-diff overlay; fall back to per-hunk + **CodeLens**). Edit the proposal side; on Keep, apply to the "live" doc and attribute + machine-vs-tweak by diffing final ↔ canned ↔ baseline. +- **PASS:** proposed side is editable; Keep applies the *tweaked* text; attribution + splits correctly; live doc untouched until Keep. +- **Decides:** Q2 (stable ceiling vs CodeLens fallback), Q7 (Keep/Undo after free + cross-hunk edits). **If FAIL:** the accept/reject surface design changes — know now. + +### E2 — Baseline router (git HEAD + snapshot) +- **Assumption (INV-7):** a `QuickDiffProvider` against a `cowriting-baseline:` doc + shows gutter bars + "Open Changes"; the original resolves from **git `HEAD`** when + tracked and from a **snapshot** otherwise; the diff goes **clean on commit / + Mark-Reviewed**. +- **Build:** register the provider; for a repo file read `HEAD` via the Git extension + API and recompute on `repository.state.onDidChange`; for a `~/Downloads` / untitled + file use a stored/in-memory snapshot. Commit (git) and "Mark Changes as Reviewed" + (snapshot) → confirm the diff clears. +- **PASS:** both modes render the expected diff; both resets clear it; works for an + untitled doc. + +### E3 — Preview authorship via markdown-it +- **Assumption (PUC-3, D11):** a contributed `markdown.markdownItPlugins` / + `extendMarkdownIt` plugin injects per-span **authorship colors + deletions** into the + **built-in** Markdown preview, toggled by a setting/command, with no custom webview. +- **Build:** contribute the plugin; feed canned attributions/changes; render + green/blue + strikethrough; toggle `cowriting.annotations` on/off. +- **PASS:** marks render inside the native preview; toggle works; deletions show; + scroll-sync intact. **If FAIL:** authorship-surface design changes. + +### E4 — Comment → reply → offer → proposal loop +- **Assumption (PUC-8, D10):** a Comments-API thread on a coedited doc can fire a turn, + post a **machine reply `Comment`**, and convert an accepted **offer** into a pending + proposal (E1's surface). Also: a **preview selection → native thread on source** via + the markdown-it token `.map` (D15). +- **Build:** create a thread on selection (and from a preview selection mapped to + source); on add, run a stubbed-or-minimal turn; post a reply comment with an + "Make this edit" action that opens an E1 proposal. +- **PASS:** reply appears in-thread; offer→proposal works; preview-initiated thread + lands on the correct source range. *(Feel/latency notes captured.)* + +### E5 — Discoverability (title bar + status bar) +- **Assumption (INV-13):** the editor **title-bar** actions (`editor/title` menus) and + a **`StatusBarItem`** (`✦ Coediting · N changes`, click → review) are visible and + obvious without the Source Control pane; everything gates on `cowriting.isCoediting`. +- **Build:** contribute the menus + status-bar item gated on the context key; enter/exit + coediting flips them. +- **PASS:** a first-time (non-git) user can find "review changes" without opening Source + Control. *(Cheapest experiment — fold into the others.)* + +## Output + +A short **findings report** (PASS / PASS-with-fallback / FAIL per experiment, with the +feel notes for E1/E4) and, for any non-PASS, a concrete **spec delta** applied to +`coauthoring-native-surfaces.md` — explicitly resolving open questions **Q2, Q4, Q7**. +Then the code is deleted and delivery moves to rung 3 (vertical slice). + +## Mapping to the design + +| Experiment | Validates | Closes | +| --- | --- | --- | +| E1 | INV-12 · editable proposals + Keep/Undo | Q2, Q7 | +| E2 | INV-7 · baseline router (HEAD + snapshot) | — | +| E3 | PUC-3 / D11 · preview authorship | — | +| E4 | PUC-8 / D10 / D15 · comment loop + preview-initiated thread | — | +| E5 | INV-13 · title-bar / status-bar discovery | — | +| (any FAIL needing a non-native surface) | INV-3 escape hatch | Q4 | diff --git a/specs/coauthoring-native-surfaces.md b/specs/coauthoring-native-surfaces.md index 0bdcb6e..1e8882c 100644 --- a/specs/coauthoring-native-surfaces.md +++ b/specs/coauthoring-native-surfaces.md @@ -889,13 +889,34 @@ contract that must be carried. ### 7.1 Approach / strategy -This is a **design-only north star**: it produces no implementation plan and ships -no code. When the operator decides to act on it, the build order follows the surface -mapping — stand up the pure cores, then **the diff surface** (smallest, -highest-confidence native win), then **the preview extension**, then **the -multi-diff accept/reject** (largest API-boundary risk — do it last, with the -CodeLens fallback ready). Each delivered increment is one SPEC → one plan → one -execution once decomposed. +This is a **design-only north star** — it ships no code. Delivery proceeds in **four +de-risking rungs, riskiest-API-assumption first**, so any forced design change is +discovered on throwaway code rather than after the full build (the explicit goal: +post-ship iteration is *polish*, not *design*): + +1. **Static mockups (done).** Validate visual design + state coverage. *(Already + surfaced and closed the empty-state, comments-from-preview, and discoverability + gaps.)* +2. **Throwaway feasibility spike (next).** A disposable VS Code extension (a §5.3 + *prototype*; the machine **stubbed** with canned edits) whose only job is to prove + the API-dependent assumptions on the real surfaces and return a **go/no-go per + assumption — closing the build-time open questions (Q2, Q4, Q7) before any plan is + written.** Riskiest first: (a) the multi-diff proposed side is **editable** with + working **Keep/Undo** (INV-12); (b) the **baseline router** renders QuickDiff + against a snapshot *and* git `HEAD`, going clean on commit / Mark-Reviewed (INV-7); + (c) the **`markdown-it`** plugin injects authorship + deletions in the built-in + preview with a toggle (PUC-3); (d) the **comment → reply → offer → proposal** loop + (PUC-8); (e) the **title-bar + status-bar** discoverability reads as obvious + (INV-13). Companion: `coauthoring-feasibility-spike.md`. Output: a findings report + + any spec deltas folded back here. +3. **Vertical slice.** One real end-to-end flow (enter → Ask Claude via the **real + `@cline/sdk`** → real proposal → review → keep) on a real document, minimal + breadth — proving the loop works for real once the surfaces are validated. +4. **Full build.** The implementation plan decomposed from this (spike-revised) spec, + built surface-by-surface in the validated order: **pure cores → diff surface** + (highest-confidence native win) **→ preview extension → multi-diff accept/reject** + (largest API-boundary risk, last, with the CodeLens fallback ready). One SPEC → + one plan → one execution per increment. ### 7.2 Rollout / launch plan