Guide Collaborative Document Creation

This skill provides a structured workflow for guiding users through collaborative document creation, acting as an active guide through three stages: Context Gathering, Refinement & Structure, and Reader Testing. It's offered when a user mentions writing documentation ("write a doc," "draft a proposal," "PRD," "design doc," "RFC") or starts a substantial writing task - explaining the three stages upfront and letting the user choose this structured approach or work freeform.

Stage 1 (Context Gathering) closes the gap between what the user knows and what Claude knows. It starts with meta-context questions (document type, primary audience, desired impact, template/format, other constraints), fetching a shared template or existing document via available integrations if mentioned, and checking for images without alt-text in existing shared docs (offering to generate alt-text from pasted images). It then encourages an unstructured info dump covering background, related discussions, why alternatives were rejected, organizational context, timeline pressures, technical architecture, and stakeholder concerns - pulled directly via Slack/Teams/Google Drive/SharePoint/MCP integrations where available, or suggested as Claude connector setup otherwise. Once the initial dump is done, it asks 5-10 numbered clarifying questions based on context gaps, answerable in shorthand, exiting this stage once questions can probe edge cases and trade-offs without needing basics re-explained.

Stage 2 (Refinement & Structure) builds the document section by section, starting with whichever section has the most unknowns (the core proposal for decision docs, the technical approach for specs, summaries saved for last). After agreeing on section structure, it creates a scaffold (an artifact via create_file, or a markdown file in the working directory) with placeholder text per section. For each section it runs six steps: clarifying questions (5-10, section-specific), brainstorming (5-20 numbered options depending on complexity), curation (the user keeps/removes/combines options with brief justifications, e.g. "Keep 1,4,7,9" or "Combine 11 and 12" - or gives freeform feedback that gets parsed), a gap check for anything missing, drafting via str_replace into the placeholder, and iterative refinement via targeted edits (never reprinting the whole document) until the user is satisfied - with a quality check after 3 consecutive no-substantial-change iterations asking what can be cut. As sections complete, it tracks the user's editing preferences to improve efficiency on later sections. Near completion (80%+ sections done), it re-reads the entire document for flow, consistency, redundancy, contradictions, and generic filler, then does one final coherence pass before offering to move to Reader Testing.

Stage 3 (Reader Testing) verifies the document works for readers with no context bleed. With sub-agent access (e.g. in Claude Code), it predicts 5-10 realistic reader questions, tests each against a fresh sub-agent given only the document plus the question, summarizes what the fresh reader got right or wrong, runs additional checks for ambiguity/false assumptions/contradictions, and loops back to refine any sections that caused confusion. Without sub-agent access (e.g. claude.ai web), it walks the user through doing this manually in a separate fresh Claude conversation with the same question set and follow-up checks. The exit condition either way: the fresh reader consistently answers correctly with no new gaps surfacing.

After Reader Testing passes, the Final Review step recommends the user do their own final read-through (since they own the document's quality), double-check facts/links/technical details, and confirm it achieves the intended impact - then offers tips like linking the authoring conversation in an appendix and updating the doc as real reader feedback arrives.

Its guidance tips: be direct and procedural rather than trying to "sell" the approach; let users skip stages or work faster if frustrated, always preserving their agency; proactively ask about gaps as they surface rather than letting them accumulate; use create_file for full section drafts and str_replace for all edits (never artifacts for brainstorming lists, which stay conversational); and prioritize quality over speed, since the goal is a document that actually works for readers, not just movement through the stages.

Use this skill when the user mentions writing documentation - drafting a proposal, spec, PRD, design doc, decision doc, or RFC - or otherwise starts a substantial writing task and wants a structured co-authoring process rather than working freeform.

Inputs: a documentation task (type, audience, desired impact) plus unstructured context (background, discussions, constraints, stakeholder concerns) provided by the user.

Outputs: a fully drafted, section-refined document (as an artifact or file) that has passed fresh-reader testing for clarity, consistency, and freedom from ambiguity or contradictions.

Slack, Teams, Google Drive, SharePoint, or other MCP-connected document/messaging sources for context gathering; create_file/str_replace for artifact or file drafting; sub-agents for automated reader testing.

Users writing substantial documents (specs, proposals, decision docs, RFCs) who want a structured, collaborative drafting process that ends with fresh-reader validation before sharing.