doc-coauthoring

Doc Co-Authoring

Turn partial context into a clear document by following a staged workflow. Keep the user in control of decisions, and optimize for a doc that works for readers who do not share the author’s context.

Triggers

Use this workflow when the user asks to:

• write or refine documentation, proposals, RFCs, PRDs, decision docs, specs
• “summarize our discussion into a doc”
• “make this readable for others” / “share with the team”
• create a template or standard for recurring documents

If the user explicitly wants freeform writing, keep the workflow lightweight (ask fewer questions; draft faster).

---

The Workflow (3 stages)

Stage 1 — Context Capture (close the gap)

Goal: collect the minimum context required to write a doc that is correct, scoped, and actionable.

Ask for:

1. Doc type + goal: what is this document for, and what decision/action should it unlock?
2. Audience: who will read it, and what do they already know?
3. Constraints: deadlines, non-goals, dependencies, security/compliance, platform limits.
4. Current state: what exists today? what’s broken? what’s missing?
5. Options considered: at least 1–2 alternatives and why they may/ may not work.
6. Success criteria: how we know it worked (metrics, user outcomes, acceptance tests).
7. Open questions: unknowns that block writing certain sections.

Output of Stage 1:

• a short “context snapshot”
• a list of open questions (ranked by importance)
• a proposed doc outline (1 screen)

Stage 2 — Outline-First Drafting (iterate by section)

Goal: draft a document in layers without losing coherence.

Rules:

• Outline before prose. Do not write full paragraphs until the outline is agreed.
• One section at a time. Draft → review → revise, then move on.
• Maintain a decision log (small bullet list) so changes are explicit.
• Keep unknowns visible: unresolved items stay in an “Open Questions / Risks” section, not hidden.

Recommended iteration loop per section:

1. Write a 3–7 bullet “section intent” (what this section must answer).
2. Draft the section (short, concrete).
3. Ask the user for a quick pass: “What’s wrong / missing / too detailed?”
4. Revise and update the decision log.

Stage 3 — Reader Testing (catch blind spots)

Goal: validate readability and completeness for a reader without the author’s context.

Method: