---
name: doc_coauthoring
description: Run a structured human-AI co-authoring workflow for docs, proposals, RFCs, PRDs, and specs. Use when the user starts a substantial writing task: "write a doc", "draft a proposal", "create a spec", "write up the RFC", or similar. Guides context gathering, section-by-section drafting, and fresh-reader testing through explicit stage gates instead of freeform drafting.
---

# Doc Co-Authoring

## Purpose
Take substantial documents (specs, proposals, RFCs, PRDs, decision docs, design docs) from idea to reader-ready without the usual failure modes: missing context, section drift, and blind spots the authors cannot see. The workflow runs three stages with hard gates. No stage advances until its exit checklist passes. The checklists, interview scripts, and test protocols live in `references/`; read the one for the stage you are entering.

## Workflow

### Stage 0: Offer
When the user seems to be starting a substantial doc ("write a doc", "draft a proposal", "create a spec", "write up", or a named type like PRD, design doc, decision doc, RFC):
1. Offer the structured workflow in three one-line stages: Context Gathering, Section Drafting, Reader Testing.
2. If they decline, work freeform. If they accept, run `bin/intake.py` (or use the scripts in `references/context-gathering-scripts.md`) and proceed to Stage 1.

### Stage 1: Context Gathering
Goal: close the gap between what the user knows and what you know, so later guidance is smart.
1. Run the meta-context interview (script in `references/context-gathering-scripts.md`, or `bin/intake.py`): doc type, audience, the reader's desired action, template choice, constraints.
2. Invite the info dump. Tell the user to dump everything unstructured. Pull from channels, threads, or shared docs the tools can reach.
3. Ask 5-10 numbered clarifying questions on the gaps. Accept shorthand answers.
4. **Gate 1** (entry to drafting): the exit checklist in `references/stage-gates.md` must pass. If it fails, name the missing pieces and keep gathering.

### Stage 2: Section Drafting
Goal: a complete, coherent draft built section by section.
1. Agree the section list. Suggest 3-5 sections from `references/doc-templates.md` for the doc type. Start with the section holding the most unknowns (usually the core decision or approach); write summaries last.
2. Per section: ask 3-5 clarifying questions, brainstorm numbered options, let the user curate (keep / remove / combine), draft, then refine with surgical edits until stable. After 3 iterations with no substantial change, ask what can be cut.
3. Run the four-level revision pass: document, paragraph, sentence, word (checklist in `references/stage-gates.md`).
4. **Gate 2** (entry to reader testing): the exit checklist must pass. Name any failing section and fix it before moving on.

### Stage 3: Reader Testing
Goal: verify the doc works for someone with zero context.
1. Predict 5-10 realistic reader questions using the rubric in `references/reader-testing-checklists.md`.
2. Run a fresh-reader test: a separate instance (or the user in a fresh session) reads the doc and answers the questions plus think-aloud prompts, with no access to the authoring conversation. Follow the protocol in `references/reader-testing-checklists.md`.
3. Triage findings by severity, fix them, retest the changed sections.
4. **Gate 3** (ship): the exit checklist must pass.

## Output Contract
- A draft file (artifact or markdown file) with every section drafted, all placeholders resolved, no "[TBD]" left behind.
- A reader-test report: questions asked, what the fresh reader got right and wrong, severity-rated findings, fixes applied, retest results.
- The gate log: for each gate, the date, the decision (pass / conditional / fail), and what failed if anything did.
- Nothing ships with an unpassed gate. If the user wants to skip a stage, record the skip explicitly in the report instead of pretending the gate passed.

## Operating Rules
1. Never advance a gate that fails. State which criterion failed and what would satisfy it.
2. Never invent facts, numbers, dates, or quotes. If the user has not supplied them, mark the gap or ask.
3. Prefer surgical edits over rewrites once a section is drafted. Reprinting the whole doc on every change hides drift.
4. The user owns style decisions. Note the edits they make directly and carry those preferences into later sections.
5. Test with genuinely fresh context: the reader-test instance gets the doc only, no memory of the authoring conversation. Label simulated guesses as simulated, observed results as observed, never mix them.
6. Keep this SKILL.md as the map. Read the reference file for the stage you are entering; do not paste whole references into chat.