vscode-cowriting-plugin-content/specs/coauthoring-feasibility-spike.md

---
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` — **in progress: E1/E3/E5 done, E2/E4 remain** |

---

## Status (2026-07-01, session 0063)

Three of the five experiments are built and passed in `vscode-cowriting-prototype`:

- **E1 — PASS with pivot.** VS Code does **not** render extension CodeLens inside
  a diff editor; per-hunk CodeLens works in a normal editor, and tweak-then-Keep
  attributes machine words vs. writer edits correctly. Folded back into the
  Solution Design as **D18** (the review surface is the live buffer itself,
  in-buffer pending changes — see `coauthoring-native-surfaces.md` v0.2.0).
- **E3 — PASS.** The `markdown-it` contribution renders author-colored marks +
  deletions in the built-in preview, theme-aware, with a working toggle.
- **E5 — PASS.** Title-bar + status-bar entry points read as obvious without the
  Source Control pane.
- **E2 (baseline router: QuickDiff vs git `HEAD` + snapshot) and E4 (comment →
  reply → offer → proposal) are not built yet** — now the riskiest unvalidated
  assumptions and the spike's remaining work.

## 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 |