Document Co-Authoring Workflow
Guide users through collaborative document creation using three stages: Context Gathering, Refinement & Structure, and Reader Testing.
When to Offer This Workflow
Trigger conditions:
- Writing documentation, proposals, specs, decision docs, RFCs
- Substantial writing tasks (not quick notes)
- Content that will be read by others
Offer the workflow upfront: Explain the three stages and ask if they want this structured approach or prefer freeform.
Stage 1: Context Gathering
Goal: Close the gap between what the user knows and what you know.
Initial Questions
Ask for meta-context (user can answer in shorthand):
- What type of document is this? (tech spec, decision doc, proposal)
- Who's the primary audience?
- What's the desired impact when someone reads this?
- Is there a template or format to follow?
- Any other constraints or context?
Info Dumping
Encourage the user to dump all context they have:
- Background on the project/problem
- Related discussions or documents
- Why alternatives aren't being used
- Organizational context
- Timeline pressures
- Technical architecture
Tell them: "Don't worry about organizing it - just get it all out."
Clarifying Questions
After initial dump, generate 5-10 numbered questions based on gaps:
1. What's the timeline for this decision?
2. Who are the key stakeholders who need to approve?
3. What happened when you tried approach X?
...User can answer in shorthand: "1: end of Q1, 2: eng leads + PM, 3: see #channel-name"
Exit condition: Questions show understanding - you 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, curation, and iterative refinement.
Process for Each Section
- Clarifying Questions - Ask 5-10 questions about what should be included
- Brainstorming - Generate 5-20 numbered options based on section complexity
- Curation - User indicates what to keep/remove/combine:
- "Keep 1,4,7,9" - "Remove 3 (duplicates 1)" - "Combine 11 and 12"
- Gap Check - Ask if anything important is missing
- Drafting - Write the section based on selections
- Iteration - Refine through surgical edits until satisfied
Section Ordering
Start with whichever section has the most unknowns:
- Decision docs: Usually the core proposal
- Specs: Usually the technical approach
- PRDs: Usually the problem statement
Leave summary sections for last.
Key Instruction for Users
Instead of editing the doc directly, have them indicate what to change:
- "Remove the X bullet - already covered by Y"
- "Make the third paragraph more concise"
- "Move section 3 before section 2"
This helps learn their style for future sections.
Quality Checking
After 3 consecutive iterations with no substantial changes, ask:
"Can anything be removed without losing important information?"
Stage 3: Reader Testing
Goal: Test the document with a fresh perspective to catch blind spots.
Step 1: Predict Reader Questions
Generate 5-10 questions readers might ask when discovering this document:
- What would they type into search?
- What would they ask Claude.ai?
Step 2: Test with Fresh Context
If sub-agents available: Invoke a sub-agent with just the document content and each question. Summarize what it got right/wrong.
If no sub-agents: Have user open fresh Claude conversation, paste document, ask the predicted questions. Report back what Reader Claude struggled with.
Step 3: Additional Checks
Ask (or have Reader Claude check):
- "What in this doc might be ambiguous to readers?"
- "What knowledge does this doc assume readers already have?"
- "Are there internal contradictions or inconsistencies?"
Step 4: Fix Blind Spots
For each issue found, loop back to Stage 2 refinement for that section.
Exit condition: Reader Claude consistently answers questions correctly and doesn't surface new gaps.
Final Review
When Reader Testing passes:
- Recommend they do a final read-through themselves
- Suggest double-checking facts, links, technical details
- Ask them to verify it achieves the intended impact
Final tips:
- Consider linking this conversation in an appendix
- Use appendices for depth without bloating main doc
- Update as feedback comes from real readers
Handling Deviations
| Situation | Response |
|---|---|
| User wants to skip a stage | Ask if they want to skip and write freeform |
| User seems frustrated | Acknowledge time investment, suggest faster path |
| Missing context on something mentioned | Ask proactively, don't let gaps accumulate |
| User edits doc directly | Note changes, incorporate preferences for future sections |
Tips for Effectiveness
- Be direct and procedural
- Explain rationale briefly when it affects behavior
- Don't try to "sell" the approach - just execute it
- Give user agency to adjust the process
- Quality over speed - each iteration should make meaningful improvements