---
name: doc-coauthoring
description: "Guide the user through a 3-stage workflow for co-authoring documents."
whenToUse: "User mentions writing documentation: write a doc, draft a proposal, create a spec"
---

# Skill: Doc Co-Authoring

## Description
Guide the user through a structured 3-stage workflow for co-authoring documents: PRDs, specs, proposals, decision docs, design docs, or any substantial writing. Adapted from Anthropic's doc-coauthoring skill for OpenJaw/PM context.

## When to Use
- User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
- User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC", "spec"
- User says "帮我写个文档" or "写个proposal"
- User seems to be starting a substantial writing task (not just a quick email)

## Workflow Overview
Offer the 3-stage workflow. If user declines, work freeform. If they accept:

```
Stage 1: Context Gathering → Stage 2: Refinement & Structure → Stage 3: Reader Testing
```

---

## Stage 1: Context Gathering

**Goal:** Close the knowledge gap between what the user knows and what Jon knows.

### Initial Questions (ask these first)
1. What type of document? (spec, decision doc, proposal, PRD...)
2. Who's the primary audience? (leadership, peer PMs, engineering, cross-team...)
3. What impact do you want when someone reads this?
4. Is there a template or format to follow?
5. Language preference? (English, Chinese, mixed)
6. Any other constraints?

### Info Dumping
Encourage user to dump all context — don't worry about organizing:
- Background on the project/problem
- Related discussions (can point to Teams chats/channels — Jon can read them)
- Why alternative solutions aren't being used
- Timeline pressures or constraints
- Technical architecture or dependencies
- Stakeholder concerns

**Jon's special capabilities for context gathering:**
- Read Teams chat history: `teams_read_messages`
- Read emails: `outlook_read_content` / `outlook_search`
- Search memory: `memory_search`
- Browse web for background: `web_search` / `web_fetch`

### Clarifying Questions
After initial dump, generate 5-10 numbered questions about gaps.
User can answer in shorthand: "1: yes, 2: see the Teams chat, 3: no because backwards compat"

**Exit condition:** When I can ask about edge cases and trade-offs without needing basics explained.

---

## Stage 2: Refinement & Structure

**Goal:** Build the document section by section through brainstorming and iteration.

### For Each Section:
1. **Clarifying questions** — What should this section include?
2. **Brainstorm 5-20 options** — Points, angles, data that might belong here
3. **User curates** — "Keep 1,4,7. Remove 3. Combine 11 and 12."
4. **Draft the section** — Write it out
5. **Iterate** — User gives feedback, Jon makes surgical edits
6. **Quality check** — After 3 iterations with no major changes, ask if anything can be cut

### Section Ordering
- Start with the section that has the most unknowns
- Leave summary/intro sections for last
- For decision docs: start with the core proposal
- For specs: start with the technical approach

### Near Completion (80%+ done)
Re-read entire document and check for:
- Flow and consistency across sections
- Redundancy or contradictions
- "Slop" — generic filler that doesn't carry weight
- Whether every sentence earns its place

---

## Stage 3: Reader Testing

**Goal:** Test the document with "fresh eyes" to catch blind spots.

### Steps:
1. **Predict reader questions** — Generate 5-10 questions a reader would ask
2. **Test each question** — Re-read the doc as if seeing it for the first time
3. **Check for:**
   - Ambiguity or unclear phrasing
   - Assumed knowledge that isn't stated
   - Internal contradictions
   - Missing context for new readers
4. **Report & fix** — List issues found, fix them

### Exit Condition
When the doc consistently makes sense to a "fresh reader" without needing verbal explanation.

---

## Final Steps
1. User does a final read-through (they own the document)
2. Double-check facts, links, technical details
3. Verify it achieves the intended impact

## Output Options
- Save as markdown file
- Generate as PDF (use create-pdf-report skill)
- Generate as Word document (use create-docx skill)
- Send via email (use email-with-attachment skill)

## Style Notes
- Be direct and procedural — don't oversell the process
- If user wants to skip a stage, let them
- Don't reprint the whole doc after every edit — show what changed
- Always give user agency to adjust the process
