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:
- Context Gathering: User provides all relevant context while Claude asks clarifying questions
- Refinement & Structure: Iteratively build each section through brainstorming and editing
- Reader Testing: Test the doc with a fresh Claude (no context) to catch blind spots before others read it
Explain that this approach helps ensure the doc works well when others read it (including when they paste it into Claude). Ask if they want to try this workflow or prefer to work freeform.
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:
- What type of document is this? (e.g., technical spec, decision doc, proposal)
- Who's the primary audience?
- What's the desired impact when someone reads this?
- Is there a template or specific format to follow?
- Any other constraints or context to know?
Inform them they can answer in shorthand or dump information however works best for them.
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.
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.
Explain that the document will be built section by section. For each section:
- Clarifying questions will be asked about what to include
- 5-20 options will be brainstormed
- User will indicate what to keep/remove/combine
- The section will be drafted
- It will be refined through surgical edits
For each section:
- Clarifying Questions - Ask 5-10 clarifying questions about what should be included
- Brainstorming - Brainstorm 5-20 things that might be included
- Curation - Ask which points should be kept, removed, or combined
- Gap Check - Ask if there's anything important missing
- Drafting - Draft the section based on selections
- Iterative Refinement - Make edits based on feedback
Continue iterating until user is satisfied with the section.
Stage 3: Reader Testing
Goal: Test the document with a fresh Claude (no context bleed) to verify it works for readers.
Test to see if the document actually works for readers. This catches blind spots - things that make sense to the authors but might confuse others.
Testing Approach
- Predict Reader Questions - Generate 5-10 questions that readers would realistically ask
- Test with Sub-Agent - Test questions with a fresh Claude instance (no context from this conversation)
- Run Additional Checks - Check for ambiguity, false assumptions, contradictions
- Report and Fix - Report issues and fix gaps
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, announce the doc has passed testing. Before completion:
- Recommend they do a final read-through themselves - they own this document and are responsible for its quality
- Suggest double-checking any facts, links, or technical details
- Ask them to verify it achieves the impact they wanted