---
name: doc-coauthoring
description: "Guide the user through a structured co-authoring workflow for writing documentation, proposals, technical specs, decision documents, how-to guides, blog posts, or any substantial piece of writing. Use this skill when the user wants to write or improve a document and needs more than a quick draft — especially when the topic is complex, the audience matters, or the stakes are high. Trigger when the user says things like 'help me write', 'I need to draft', 'co-author', 'let's write together', or when they describe a document they need to produce."
---

# Doc Co-Authoring Skill

Guide the user through three stages. Do not rush — each stage should produce meaningful progress before moving to the next.

## Stage 1: Context Gathering

Start by understanding the full picture before writing a single word.

Ask meta-context questions:
- What type of document is this? (blog post, how-to guide, proposal, spec, policy, announcement, FAQ, case study)
- Who is the audience? (site visitors, customers, team members, stakeholders, a specific person)
- What should the reader DO or FEEL after reading it?
- Are there any constraints? (word count, tone, existing template, deadline, SEO keywords)
- Does a draft or outline already exist?

Then invite an information dump:
> "Tell me everything relevant — background, what you've already decided, what's still unclear, why alternatives were rejected, who needs to sign off. Don't worry about structure yet."

Follow up with 5–10 targeted questions to fill gaps — especially around edge cases, the reader's likely objections, and what success looks like.

Exit Stage 1 when you have enough to build a skeleton that reflects real decisions, not placeholders.

## Stage 2: Refinement and Structure

Build the document section by section through iteration.

1. **Scaffold first** — propose a section outline with headers and one-line descriptions. Get the user's approval before writing any body text.
2. **Draft section by section** — for each section, ask 2–3 clarifying questions, write a draft, invite feedback, revise.
3. **Edit in place** — quote the exact passage you are replacing and show the replacement. Never reprint the entire document unless asked.
4. **After 3 stable passes**, ask: "Is there anything we can cut without losing meaning?"

Quality checks for each section:
- Does it serve the stated audience?
- Is every claim backed by something the user told you (not assumed)?
- Is the reading level appropriate?
- Are there unnecessary hedges, repetitions, or filler phrases?

## Stage 3: Reader Testing

Test the document against a fresh perspective.

Generate 5–10 questions a real reader might ask after reading the document — things that are ambiguous, assumed without being stated, or that contradict each other.

Work through each question with the user:
- Could a reader answer this from the document alone?
- If not, decide: add clarity, cut the ambiguity, or accept the gap with intent.

Repeat until the document answers its own key questions without the author in the room.

## Throughout

- Keep the user in control — present options, not directives.
- Match the writing style to what the user tells you, not to a generic "professional" default.
- For WordPress content: respect the site's existing voice and any SEO requirements the user mentions.
- If the document will be published as a WordPress post or page, ask whether SEO title, meta description, or excerpt copy is also needed — and write those too.
