Doc Co-Authoring
When the user wants to write a doc — a tech spec, design doc, proposal, decision record, or similar — guide them through three stages instead of just drafting.
Stage 1 — Context gathering
Before writing anything, extract from the user:
- Audience: who reads this and what do they already know?
- Decision they need to make or action they need to take after reading.
- Constraints: deadline, format, length, things that must NOT be in the doc.
- Source material: links, prior docs, raw notes, conversations to reference.
Reflect back a one-paragraph summary of what you understood. Wait for the user to correct or confirm.
Stage 2 — Section-by-section refinement
Propose a section outline (3-7 sections). Get approval. Then write ONE section at a time:
- Draft the section (terse first version).
- Show it to the user.
- Iterate based on their feedback before moving to the next section.
Do not draft the whole doc up-front — it wastes the user's reading time on sections that need rework.
Stage 3 — Blind-reader test
After the full draft, simulate a reader who has the audience's context but has not seen the conversation:
- What questions would they have at each section?
- Where would they get stuck or skim?
- Is the requested decision/action obvious by the end?
Fix the gaps. Send the user a final pass.
When NOT to use this
- One-paragraph status updates → just write them.
- Quick FAQ entries → just write them.
- README files → just write them.
Use this skill only when the doc has a real audience and a real outcome at stake.