Doc Coauthoring

<!-- AUTO-GENERATED by export-plugins.py — DO NOT EDIT -->
---
name: doc-coauthoring
description: Structured collaborative document creation through context gathering, iterative refinement, and reader testing. Use when co-authoring documentation, proposals, technical specs, decision docs, or RFCs.
tags: [documentation, writing, collaboration, specs]
---

# Doc Co-Authoring Workflow

This skill provides a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

## When to Offer This Workflow

**Trigger conditions:**
- 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"
- User seems to be starting a substantial writing task

**Initial offer:**
Offer the user a structured workflow for co-authoring the document. Explain the three stages:

1. **Context Gathering**: User provides all relevant context while Claude asks clarifying questions
2. **Refinement & Structure**: Iteratively build each section through brainstorming and editing
3. **Reader Testing**: Test the doc with a fresh Claude (no context) to catch blind spots before others read it

If user declines, work freeform. If user accepts, proceed to Stage 1.

## Stage 1: Context Gathering

**Goal:** Close the gap between what the user knows and what Claude knows, enabling smart guidance later.

### Initial Questions

Start by asking the user for meta-context about the document:

1. What type of document is this? (e.g., technical spec, decision doc, proposal)
2. Who's the primary audience?
3. What's the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

Inform them they can answer in shorthand or dump information however works best for them.

**If user provides a template or mentions a doc type:**
- Ask if they have a template document to share
- If they provide a link to a shared document, use the appropriate integration to fetch it
- If they provide a file, read it

**If user mentions editing an existing shared document:**
- Use the appropriate integration to read the current state
- Check for images without alt-text
- If images exist without alt-text, explain that when others use Claude to understand the doc, Claude won't be able to see them. Ask if they want alt-text generated.

### Info Dumping

Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:
- Background on the project/problem
- Related team discussions or shared documents
- Why alternative solutions aren't being used
- Organizational context (team dynamics, past incidents, politics)
- Timeline pressures or constraints
- Technical architecture or dependencies
- Stakeholder concerns

Advise them not to worry about organizing it - just get it all out.

**During context gathering:**

- If user mentions entities/projects that are unknown:
  - Ask if connected tools should be searched to learn more
  - Wait for user confirmation before searching

- As user provides context, track what's being learned and what's still unclear

**Asking clarifying questions:**

When user signals they've done their initial dump, ask clarifying questions:

Generate 5-10 numbered questions based on gaps in the context.

Inform them they can use shorthand to answer (e.g., "1: yes, 2: see #channel, 3: no because backwards compat").

**Exit condition:**
Sufficient context has been gathered when questions show understanding - when edge cases and trade-offs can be asked about without needing basics explained.

## Stage 2: Refinement & Structure

**Goal:** Build the document section by section through brainstorming, curation, and iterative refinement.

**For each section:**

### Step 1: Clarifying Questions

Ask 5-10 clarifying questions about what should be included in the section.

### Step 2: Brainstorming

Brainstorm 5-20 things that might be included, depending on section complexity. Look for:
- Context shared that might have been forgotten
- Angles or considerations not yet mentioned

### Step 3: Curation

Ask which points should be kept, removed, or combined. Request brief justifications.

### Step 4: Gap Check

Ask if there's anything important missing for the section.

### Step 5: Drafting

Draft the section based on curated selections.

### Step 6: Iterative Refinement

As user provides feedback:
- Make surgical edits (never reprint the whole doc)
- If user edits doc directly, note the changes for future sections

**Continue iterating** until user is satisfied with the section.

### Quality Checking

After 3 consecutive iterations with no substantial changes, ask if anything can be removed without losing important information.

### Near Completion

As approaching completion (80%+ of sections done), re-read the entire document and check for:
- Flow and consistency across sections
- Redundancy or contradictions
- Anything that feels like generic filler
- Whether every sentence carries weight

## Stage 3: Reader Testing

**Goal:** Test the document with a fresh Claude (no context bleed) to verify it works for readers.

### Step 1: Predict Reader Questions

Generate 5-10 questions that readers would realistically ask.

### Step 2: Test with Sub-Agent

For each question, invoke a sub-agent with just the document content and the question.

Summarize what Reader Claude got right/wrong for each question.

### Step 3: Run Additional Checks

Invoke sub-agent to check for ambiguity, false assumptions, contradictions.

### Step 4: Report and Fix

If issues found, loop back to refinement for problematic sections.

### Exit Condition

When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the doc is ready.

## Final Review

When Reader Testing passes:

1. Recommend they do a final read-through themselves
2. Suggest double-checking any facts, links, or technical details
3. Ask them to verify it achieves the impact they wanted

## Anti-Patterns

- Skipping context gathering and jumping straight to writing
- Writing entire documents in one shot without iterative review
- Not testing the document with a fresh reader perspective
- Ignoring organizational context and stakeholder concerns
- Over-polishing early sections while later sections remain empty

## References

- [Google Technical Writing](https://developers.google.com/tech-writing)
- [Divio Documentation System](https://documentation.divio.com/)

<!-- Source: .faos/custom/skills/documentation/doc-coauthoring/SKILL.md -->