--- name: doc-coauthoring description: >- Three-stage workflow for co-authoring a substantive document with a user: (1) Context Gathering with meta-questions + info dump + clarifying questions; (2) Refinement section-by-section with clarify → brainstorm → curate → draft → surgical edits; (3) Reader Testing where a fresh assistant or subagent reads the doc cold and answers predicted reader questions to surface blind spots. Pairs with `technical-writer`, `legal-researcher`, and `tax-researcher` agents. USE FOR: co-author a document, write a spec, write a design doc, write a PRD, write an RFC, write a decision doc, write a proposal, draft a post-mortem, draft a Schriftsatz, section-by-section drafting, reader test a document, doc blind spot check, refine doc iteratively, info-dump workflow, brainstorm section options, surgical edit, fresh-eyes review. DO NOT USE FOR: short emails, code review, README authoring, pure copy editing (use `grammar-check`). --- # Doc Co-Authoring Workflow Guide a user through writing a long, high-stakes document by alternating between question-driven context gathering, structured per-section drafting, and a fresh-eyes reader test before declaring done. Active guide, not freeform brainstorm. ## When to Use - User says: "draft a spec", "write a design doc", "help me write a proposal", "draft an RFC", "draft a Schriftsatz", "draft a memo". - The deliverable will be read by people who weren't in the original conversation. - The user has context the assistant lacks (org politics, prior incidents, tacit knowledge). - The doc is long enough that drafting it as one blob produces incoherent results (typically > ~2 pages). ## When NOT to Use - The user wants a quick paragraph or an email. Just write it. - The doc is purely factual and the user has zero hidden context (e.g., "summarise these meeting notes"). The intermediate stages waste time. - The user explicitly asks for freeform back-and-forth. Honour that. ## Opening offer On first invocation, surface the workflow and let the user opt in: > I can take you through a structured co-authoring loop in three stages: (1) context gathering, (2) section-by-section drafting with brainstorm + curate, (3) a reader-test pass with a fresh assistant. It usually produces a tighter doc than freeform drafting. Want to use it, or prefer freeform? If the user declines, write freeform. If accepted, run Stage 1. ## Interaction style When interviewing the user (clarifying questions in Stage 1, section-choice prompts in Stage 2, reader-test questions in Stage 3), follow the shared convention in [`Reference/interactive-questions.md`](../../Reference/interactive-questions.md): prefer `vscode_askQuestions` over markdown checkboxes when the tool is available. ## Stage 1 — Context Gathering Goal: close the gap between what the user knows and what you know. ### 1a. Meta-questions (always ask) 1. Document type? (spec, decision doc, RFC, Schriftsatz, post-mortem, …) 2. Primary audience? (engineering peers, executives, an opposing counsel, a regulator, …) 3. What should the reader do or decide after reading? 4. Is there a template, prior doc, or style guide to match? 5. Hard constraints (length, format, jurisdiction, classification)? State that shorthand answers are fine. ### 1b. Info dump Invite an unstructured dump of everything the user knows: background, prior decisions, org dynamics, related discussions, timeline pressure, technical constraints, stakeholders. Tell the user not to organise it. Offer concrete ways to dump: stream of consciousness, links to threads/docs, paste of meeting notes, file attachments. If MCP / connector tools are available (Outlook, GitHub, Sharepoint, Confluence), mention you can pull context directly. ### 1c. Clarifying questions When the user signals they're done dumping (or after a substantial dump), generate 5-10 numbered clarifying questions targeting actual gaps. Let them answer in shorthand ("1: yes, 2: see #thread, 3: skip…"). Iterate until your follow-up questions are about edge cases and trade-offs, not basics — that's the exit signal. Ask: "Anything else, or shall we move to drafting?" ## Stage 2 — Refinement (section by section) Goal: produce one tight section at a time through structured iteration. ### 2a. Agree the section list Propose 3-7 sections appropriate to the doc type. Examples: - **Decision doc:** Context → Decision → Alternatives Considered → Consequences → Open Questions. - **Technical spec:** Problem → Goals / Non-goals → Approach → Trade-offs → Migration → Risks. - **Schriftsatz / legal memo:** Sachverhalt → Rechtliche Würdigung → Anträge → Anlagen. - **Post-mortem:** Timeline → Impact → Root cause → What went well → Action items. Confirm the structure. Create a placeholder skeleton in the target file (or as an artifact) with `[To be written]` per section. Suggest starting with the section that has the most unknowns — usually the core decision or the technical approach. Summaries last. ### 2b. Per-section loop For each section, run five steps: 1. **Clarify.** 3-7 numbered questions targeting what this specific section needs. Shorthand answers welcome. 2. **Brainstorm.** Propose 5-20 numbered options for what this section could include. Cover obvious points and missed angles. Offer more on request. 3. **Curate.** User indicates keep/remove/combine. Parse freeform feedback too ("keep 1-3, drop 5, merge 7+8"). Note their priorities — they transfer to later sections. 4. **Gap check.** "Anything missing for this section?" 5. **Draft.** Edit the placeholder in place. Ask the user to read and tell you what to change — specifically not to edit it directly, so you learn their style. They may still edit; if they do, note the deltas as style signal for later sections. Iterate by **surgical edits** (one block at a time). Do not reprint the whole document. If iteration plateaus after ~3 rounds, ask: "Anything we can cut without losing meaning?" Mark the section done. Move to the next. ### 2c. Coherence pass At ~80% of sections complete, read the whole document and surface: contradictions, redundant content, generic filler, sentences that don't carry weight. Apply or propose fixes. ## Stage 3 — Reader Testing Goal: catch blind spots before someone outside the conversation reads it. ### 3a. Predict reader questions Generate 5-10 questions a real reader would ask after reading the doc cold. Include the obvious ("what is this proposing?") and the harder ("what happens to the X system after this change?"). ### 3b. Run the test Two options depending on tooling: - **With subagent / fresh chat available.** Spawn a subagent (use `runSubagent`) passing only the document text and one question. Repeat per question. Capture answers. - **No subagent.** Tell the user to open a fresh chat (https://chat.openai.com or a clean Copilot chat), paste the doc, and ask the predicted questions one at a time. Report findings back. Also ask the fresh reader explicitly: - What in this doc is ambiguous or unclear? - What background knowledge does the doc assume? - Are there contradictions or inconsistencies? ### 3c. Triage and fix For each wrong answer or surfaced gap, loop back to Stage 2 for the affected section. Re-run reader testing on changed sections. Done when the fresh reader answers correctly and surfaces no new gaps. ## Final review Before declaring complete: 1. User does a final read-through. They own the doc. 2. User verifies facts, links, names, numbers. 3. User confirms the doc achieves the stated impact (the Stage-1 question 3 answer). Optional close-out tips for the user: - Link the originating chat as an appendix so readers can audit how the doc was assembled. - Push depth into appendices; keep the main body lean. - Treat the first release as a draft — update with real-reader feedback. ## Tone and operating rules - Direct, procedural. Don't sell the workflow — just run it. - Explain rationale only when it changes user behaviour ("don't edit the draft directly so I learn your style"). - Always give the user agency to skip a stage or revert to freeform. - Use surgical edits (`str_replace` semantics), never reprint the whole doc. - Never use placeholders like `[fill in details]` in the final draft. If a section can't be drafted, ask, don't fake. ## Common pitfalls - **Skipping Stage 1.** Drafting without context produces plausible-sounding nonsense. - **Brainstorming as a single dense paragraph.** Numbered lists are essential for the curate step. - **Iterating forever on Section 1.** Move on when the section is good enough; coherence pass catches residuals. - **Skipping Stage 3.** The fresh-reader test is the single most valuable step; subagents make it cheap. - **Treating the doc as the assistant's output.** It's the user's deliverable. They own facts, claims, and final wording.