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:
- Doc type + goal: what is this document for, and what decision/action should it unlock?
- Audience: who will read it, and what do they already know?
- Constraints: deadlines, non-goals, dependencies, security/compliance, platform limits.
- Current state: what exists today? what’s broken? what’s missing?
- Options considered: at least 1–2 alternatives and why they may/ may not work.
- Success criteria: how we know it worked (metrics, user outcomes, acceptance tests).
- 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:
- Write a 3–7 bullet “section intent” (what this section must answer).
- Draft the section (short, concrete).
- Ask the user for a quick pass: “What’s wrong / missing / too detailed?”
- 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:
- Prepare a clean-context review prompt: “You are a reviewer with no prior context. Read this doc and identify: missing context, unclear terms, ambiguous decisions, hidden assumptions, and where you’d ask questions.”
- If sub-agents are available, run the review in a fresh agent session. Otherwise, run the review yourself by explicitly pretending you have no access to prior conversation.
Output of Stage 3:
- a short list of fixes (highest leverage first)
- revised doc with clarified assumptions, terms, and decisions
Default Section Templates
Load references/templates.md and pick the closest template:
- Decision record (ADR-lite)
- Product requirements (PRD-lite)
- Technical design / RFC
- Proposal / pitch
Quality Bar (what to optimize for)
The doc should make it easy for a reader to answer:
- What problem are we solving, for whom, and why now?
- What are we proposing, and what are we not doing?
- What options did we consider, and what tradeoffs drive the choice?
- What are the risks, unknowns, and mitigations?
- What are the next steps and owners?
1---2name: doc-coauthoring3description: A structured workflow for co-authoring high-signal docs (PRD, RFC, design docs, proposals, decision records). Use when the user needs to turn messy context into a readable artifact with clear goals, tradeoffs, and next steps. Emphasizes context capture, outline-first drafting, and context-free reader testing to catch blind spots.4license: Complete terms in LICENSE.txt5---67# Doc Co-Authoring89Turn 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.1011## Triggers1213Use this workflow when the user asks to:1415- write or refine documentation, proposals, RFCs, PRDs, decision docs, specs16- “summarize our discussion into a doc”17- “make this readable for others” / “share with the team”18- create a template or standard for recurring documents1920If the user explicitly wants freeform writing, keep the workflow lightweight (ask fewer questions; draft faster).2122---2324## The Workflow (3 stages)2526### Stage 1 — Context Capture (close the gap)2728Goal: collect the minimum context required to write a doc that is correct, scoped, and actionable.2930Ask for:31321. **Doc type + goal**: what is this document for, and what decision/action should it unlock?332. **Audience**: who will read it, and what do they already know?343. **Constraints**: deadlines, non-goals, dependencies, security/compliance, platform limits.354. **Current state**: what exists today? what’s broken? what’s missing?365. **Options considered**: at least 1–2 alternatives and why they may/ may not work.376. **Success criteria**: how we know it worked (metrics, user outcomes, acceptance tests).387. **Open questions**: unknowns that block writing certain sections.3940Output of Stage 1:4142- a short “context snapshot”43- a list of open questions (ranked by importance)44- a proposed doc outline (1 screen)4546### Stage 2 — Outline-First Drafting (iterate by section)4748Goal: draft a document in layers without losing coherence.4950Rules:5152- **Outline before prose**. Do not write full paragraphs until the outline is agreed.53- **One section at a time**. Draft → review → revise, then move on.54- **Maintain a decision log** (small bullet list) so changes are explicit.55- **Keep unknowns visible**: unresolved items stay in an “Open Questions / Risks” section, not hidden.5657Recommended iteration loop per section:58591. Write a 3–7 bullet “section intent” (what this section must answer).602. Draft the section (short, concrete).613. Ask the user for a quick pass: “What’s wrong / missing / too detailed?”624. Revise and update the decision log.6364### Stage 3 — Reader Testing (catch blind spots)6566Goal: validate readability and completeness for a reader without the author’s context.6768Method:6970- Prepare a **clean-context review prompt**: “You are a reviewer with no prior context. Read this doc and identify: missing context, unclear terms, ambiguous decisions, hidden assumptions, and where you’d ask questions.”71- If sub-agents are available, run the review in a fresh agent session. Otherwise, run the review yourself by explicitly pretending you have _no access_ to prior conversation.7273Output of Stage 3:7475- a short list of fixes (highest leverage first)76- revised doc with clarified assumptions, terms, and decisions7778---7980## Default Section Templates8182Load `references/templates.md` and pick the closest template:8384- Decision record (ADR-lite)85- Product requirements (PRD-lite)86- Technical design / RFC87- Proposal / pitch8889## Quality Bar (what to optimize for)9091The doc should make it easy for a reader to answer:9293- What problem are we solving, for whom, and why now?94- What are we proposing, and what are we not doing?95- What options did we consider, and what tradeoffs drive the choice?96- What are the risks, unknowns, and mitigations?97- What are the next steps and owners?
shareAI-lab