---
name: doc-coauthoring
description: Guide users through a structured workflow for co-authoring documentation, proposals, technical specs, decision docs, or any substantial written content. Use when user wants to write docs, create proposals, draft specs, write PRDs, RFCs, or similar structured content that benefits from collaborative iteration.
triggers:
  - write a doc
  - draft a proposal
  - create a spec
  - write up
  - PRD
  - design doc
  - decision doc
  - RFC
  - technical spec
  - write documentation
---

# Doc Co-Authoring Workflow

A structured three-stage workflow for collaborative document creation that ensures the final output works for its intended readers.

## When to Use

Trigger on requests involving substantial written content:
- Technical specifications or design documents
- Product requirements documents (PRDs)
- Proposals or RFCs
- Decision documents
- Project documentation
- Any writing task that benefits from structured iteration

## The Three Stages

### Stage 1: Context Gathering

**Goal:** Close the knowledge gap between what the user knows and what needs to be in the document.

**Process:**
1. Ask meta-context questions (one at a time, not a wall of questions):
   - What type of document is this?
   - Who is the primary audience?
   - What is the desired impact when someone reads this?
   - Is there a template or specific format to follow?
   - Any constraints or context to know?

2. Encourage an "info dump" — let the user provide all context in whatever format works:
   - Background on the project/problem
   - Related discussions or prior documents
   - Why alternatives were rejected
   - Organizational context (team dynamics, politics)
   - Timeline pressures or constraints
   - Technical architecture or dependencies
   - Stakeholder concerns

3. Ask clarifying questions based on the dump. Focus on:
   - Gaps in the narrative
   - Unstated assumptions
   - Missing audience context
   - Potential objections the doc needs to address

4. Summarize understanding back to the user before proceeding.

### Stage 2: Refinement and Structure

**Goal:** Iteratively build each section through brainstorming and editing.

**Process:**
1. Propose a document outline based on gathered context
2. Get user approval on structure before writing
3. Draft each section, presenting for feedback:
   - Write one section at a time
   - Ask "Does this capture what you mean?" after each
   - Offer 2-3 alternative framings for key points
   - Flag areas where the user's input was ambiguous

**Section-by-section approach:**
- Start with the hardest/most important section (usually the problem statement or proposal)
- Build supporting sections around the core argument
- Save introduction and summary for last (they depend on the body)

**Refinement techniques:**
- "Steel-man" potential objections and address them in the doc
- Identify where examples or data would strengthen claims
- Flag jargon that the audience might not share
- Suggest visuals or diagrams where they would clarify

### Stage 3: Reader Testing

**Goal:** Verify the document works for someone without the author's context.

**Process:**
1. Read the complete document as if encountering it fresh
2. Identify blind spots:
   - Undefined terms or acronyms
   - Logical jumps that require insider knowledge
   - Missing context that the author takes for granted
   - Sections that assume prior reading of other docs
3. Flag questions a reader would have at each point
4. Suggest specific fixes for each blind spot found
5. Final pass for:
   - Consistent terminology throughout
   - Clear section transitions
   - Actionable next steps or conclusions
   - Appropriate length for the audience

## Output

Deliver the final document as a file in the appropriate format (Markdown by default). Include:
- The complete document
- A brief "author's notes" section with decisions made and alternatives considered
- Suggested next steps (who to share with, what feedback to seek)

## Anti-Patterns to Avoid

- Writing the entire document before getting any feedback
- Asking all questions at once instead of conversationally
- Producing generic template content instead of context-specific writing
- Skipping the reader testing stage
- Over-polishing prose before the structure is right