doc-coauthoring

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

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.

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.

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.

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:

1. Clarifying questions will be asked about what to include
2. 5-20 options will be brainstormed
3. User will indicate what to keep/remove/combine
4. The section will be drafted
5. It will be refined through surgical edits

For each section:

1. Clarifying Questions - Ask 5-10 clarifying questions about what should be included
2. Brainstorming - Brainstorm 5-20 things that might be included
3. Curation - Ask which points should be kept, removed, or combined
4. Gap Check - Ask if there's anything important missing
5. Drafting - Draft the section based on selections
6. Iterative Refinement - Make edits based on feedback

Continue iterating until user is satisfied with the section.

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

1. Predict Reader Questions - Generate 5-10 questions that readers would realistically ask
2. Test with Sub-Agent - Test questions with a fresh Claude instance (no context from this conversation)
3. Run Additional Checks - Check for ambiguity, false assumptions, contradictions
4. 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.

When Reader Testing passes, announce the doc has passed testing. Before completion:

1. Recommend they do a final read-through themselves - they own this document and are responsible for its quality
2. Suggest double-checking any facts, links, or technical details
3. Ask them to verify it achieves the impact they wanted