---

name: doc-coauthoring description: Guide users through a structured workflow for co-authoring documentation through three stages: Context Gathering, Refinement & Structure, and Reader Testing. Use when user wants to write documentation, proposals, technical specs, decision docs, PRDs, RFCs, or similar structured content.

Doc Co-Authoring Workflow

Structured workflow for collaborative document creation through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

When to Offer This Workflow

Trigger conditions:

• User mentions writing docs, specs, proposals, PRDs, decision docs, RFCs
• User starting substantial writing task

Initial offer: Explain the three stages:

1. Context Gathering: User provides context, Claude asks clarifying questions
2. Refinement & Structure: Iteratively build each section
3. Reader Testing: Test with fresh Claude to catch blind spots

Ask if they want this workflow or prefer freeform. If decline, work freeform. If accept, proceed to Stage 1.

Stage 1: Context Gathering

Goal: Close gap between user's knowledge and Claude's knowledge.

Initial Questions

Ask user for meta-context:

1. Document type? (spec, decision doc, proposal)
2. Primary audience?
3. Desired impact?
4. Template or format to follow?
5. Other constraints?

If user provides template or doc type: Ask if they have a template to share. If link provided, use integration to fetch. If file, read it.

If editing existing shared doc: Use integration to read current state. Check for images without alt-text. Explain Claude can't see images without alt-text. Ask if they want alt-text generated.

Info Dumping

Encourage user to dump all context: project background, related discussions, alternatives rejected, org context, timeline pressures, technical dependencies, stakeholder concerns.

Offer multiple ways: stream-of-consciousness, point to channels, link to docs.

If integrations available: Use them to pull context directly. If no integrations: Suggest enabling connectors in settings.

Asking clarifying questions: When user signals initial dump complete, generate 5-10 numbered questions based on gaps.

Exit condition: Questions show understanding - can ask about edge cases/trade-offs without basics.

Transition: Ask if more context or ready to draft.

Stage 2: Refinement & Structure

Goal: Build document section by section.

Instructions: For each section:

1. Clarifying questions
2. Brainstorm 5-20 options
3. User indicates keep/remove/combine
4. Draft section
5. Refine through edits

Start with section with most unknowns (usually core decision/proposal).

Section ordering: If structure clear: Ask which section to start with. Suggest starting with most unknowns. If user doesn't know sections: Suggest 3-5 appropriate sections for doc type. Ask if works or needs adjustment.

Once structure agreed: Create initial document with placeholders.

If artifacts available: Use create_file to create artifact. If no artifacts: Create markdown file with placeholders.

For each section:

Step 1: Clarifying Questions

Announce work on [SECTION NAME]. Ask 5-10 specific questions.

Step 2: Brainstorming

Generate 5-20 numbered options based on complexity.

Step 3: Curation

Ask which to keep, remove, combine. Request brief justifications.

If user gives freeform feedback: Extract preferences and apply.

Step 4: Gap Check

Ask if anything important missing for [SECTION NAME].

Step 5: Drafting

Use str_replace to replace placeholder with drafted content.

Key instruction (first section): Tell user to indicate changes rather than editing directly. Helps learn style.

Step 6: Iterative Refinement

As user provides feedback, use str_replace for edits.

• If artifacts: Provide link after each edit
• If files: Confirm completion
• If user edits directly, note changes for future sections

Quality Checking: After 3 iterations with no substantial changes, ask if anything can be removed.

When section done, confirm [SECTION NAME] complete. Ask if ready for next section.

Repeat for all sections.

Near Completion

At 80%+ complete, announce intention to re-read entire document checking:

• Flow and consistency
• Redundancy/contradictions
• Generic filler
• Whether every sentence carries weight

Read and provide feedback.

When all sections done: Announce all drafted. Review for coherence, flow, completeness. Provide final suggestions. Ask if ready for Reader Testing or more refinement.

Stage 3: Reader Testing

Goal: Test with fresh Claude (no context) to verify doc works for readers.

Instructions: Explain testing catches blind spots - things making sense to authors but confusing others.

Testing Approach

If sub-agents available (Claude Code): Perform testing directly.

Step 1: Predict Reader Questions

Generate 5-10 questions readers would realistically ask.

Step 2: Test with Sub-Agent

For each question, invoke sub-agent with just document content and question. Summarize what Reader Claude got right/wrong.

Step 3: Run Additional Checks

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

Step 4: Report and Fix

If issues found: Report specific issues. Fix gaps by looping back to refinement.

---

If no sub-agents (claude.ai): User tests manually.

Step 1: Predict Reader Questions

Generate 5-10 questions readers would ask.

Step 2: Setup Testing

Instruct user to:

1. Open fresh Claude: https://claude.ai
2. Paste/share document
3. Ask Reader Claude the questions

For each question, Reader Claude provides: answer, ambiguities, assumed context.

Step 3: Additional Checks

Ask Reader Claude about ambiguities, assumed knowledge, contradictions.

Step 4: Iterate Based on Results

Ask what Reader Claude got wrong. Fix gaps by looping back to refinement.

---

Exit Condition (Both Approaches)

When Reader Claude consistently answers correctly without surfacing new gaps, doc is ready.

Final Review

When Reader Testing passes:

1. Recommend user does final read-through
2. Double-check facts, links, technical details
3. Verify achieves desired impact

Ask if one more review or done.

If done: Announce completion. Tips:

• Link conversation in appendix for context
• Use appendices for depth without bloating
• Update as feedback received

Tips for Effective Guidance

Tone: Direct, procedural. Explain rationale briefly. Don't "sell" approach.

Handling Deviations: Give user agency to skip stages or adjust process.

Context Management: Proactively ask about missing context. Don't let gaps accumulate.

Artifact Management:

• create_file for full sections
• str_replace for edits
• Provide artifact link after changes
• Never use artifacts for brainstorming

Quality over Speed: Don't rush. Each iteration should meaningfully improve. Goal is doc that actually works.