---
name: doc-coauthoring
description: Structured co-authoring workflow for PRDs, design docs, RFCs, decision docs, proposals, and any substantial written document. Use when the user wants to write a PRD, design doc, RFC, decision doc, one-pager, proposal, technical spec, or any structured document where quality and completeness matter. Goes deeper than technical-writer — this skill actively guides the writing process through three stages: context gathering, section-by-section refinement, and reader testing.
---

# Document Co-Authoring

Writing a document alone produces a document that makes sense to the author. Co-authoring produces a document that makes sense to the reader. This skill is the difference between the two.

You are an active guide, not a passive typist. You ask questions before writing. You brainstorm before drafting. You test the document against a reader before declaring it done. Every section goes through: clarify → brainstorm → curate → draft → refine.

---

## Co-Authoring Principles

- **Context first, writing second.** A document written without sufficient context will be rewritten. Spend time gathering context — it is never wasted.
- **Brainstorm before drafting.** Generating options before committing produces better decisions. Never jump straight from question to final prose.
- **One section at a time.** Trying to write the whole document at once produces mediocre everything. Perfect one section, then move to the next.
- **The reader is not in the room.** Everything the author knows implicitly, the reader does not. Surfaces those assumptions, names them, and either explains them or removes them.
- **Reader testing is not optional.** Authors cannot find their own blind spots. A fresh reader (or a fresh AI instance with no context) will find what the author cannot.
- **Documents must earn every sentence.** If a sentence can be removed without losing meaning, remove it. Dense, precise prose is harder to write and easier to read.

---

## When to Use This Skill

**Trigger conditions:**
- "Write a PRD for..."
- "Help me draft a design doc"
- "I need to write an RFC"
- "Can you write up a one-pager on..."
- "I need a decision doc for..."
- "Help me write a technical spec"
- Any substantial document where quality matters (not quick memos — use `internal-comms` for those)

**Document types this skill handles best:**

| Document | Who writes it | What it decides |
|---|---|---|
| **PRD** (Product Requirements Doc) | PM + Eng | What to build and why |
| **Design Doc** | Engineer | How to build it technically |
| **RFC** (Request for Comments) | Anyone | Propose a change and gather feedback |
| **Decision Doc** | Anyone | Capture a decision and its rationale |
| **One-pager** | PM / Exec | Make a case quickly |
| **Technical Spec** | Engineer | Define system behavior precisely |
| **Proposal** | Anyone | Convince someone to approve something |

---

## Stage 1 — Context Gathering

### Step 1: Meta questions (ask all at once)

Before writing anything, ask:

1. **What type of document?** (PRD / design doc / RFC / decision doc / other)
2. **Who is the primary audience?** (engineers, PMs, executives, external partners)
3. **What is the desired outcome when someone reads this?** (approve a plan, understand a decision, provide feedback, implement a spec)
4. **Is there a template or format to follow?** (company template, team convention)
5. **Any deadline or constraints?** (length limit, formality level, existing work to reference)

Tell the user they can answer in shorthand — a quick brain dump is fine.

### Step 2: Context dump

After meta questions, ask for everything they know:

```
Now dump everything relevant — don't worry about organizing it. I'll make sense of it.

This includes:
- Background on the problem or project
- Why existing solutions don't work
- Relevant team discussions or decisions
- Timeline and constraints
- Technical context or dependencies
- Stakeholder concerns or objections you anticipate
- What success looks like

More is better at this stage.
```

Accept input in any format: brain dump, bullet points, links to docs, pasted Slack threads, previous drafts.

### Step 3: Confirm understanding

Before moving to writing, summarize back:

```
Let me confirm I understand the core of this document:

**What:** [one sentence]
**Why:** [one sentence]  
**Who reads it:** [audience]
**What they need to conclude:** [desired outcome]
**Key constraints:** [length, tone, deadline]

Does this capture it? Anything I'm missing?
```

Only proceed when the user confirms.

---

## Stage 2 — Section-by-Section Refinement

Work through the document one section at a time. Never draft the whole document at once.

### Standard Document Structure

Adapt this to the document type, but these sections cover most cases:

```markdown
# [Document Title]

**Author:** [name] | **Date:** [date] | **Status:** Draft / In Review / Approved

## TL;DR
[2-3 sentences. The busiest reader should get the point here.]

## Background / Context
[Why does this document exist? What problem exists?]

## Goals
[What success looks like. Measurable where possible.]

## Non-Goals
[Explicit scope boundary. What this does NOT address.]

## Proposal / Approach
[The meat. What are we doing / deciding / building?]

## Alternatives Considered
[What else was considered and why it was rejected.]

## Open Questions
[What is still unresolved. Owner and due date for each.]

## Appendix
[Supporting detail that would bloat the main doc.]
```

### Per-Section Workflow

For **each section**, run this sequence:

#### Step 1: Clarifying Questions
Ask 5–8 targeted questions specific to this section. Example for "Goals":
```
For the Goals section — a few questions:
1. What does success look like in 3 months? In 6?
2. Is there a metric you'd point to as "we nailed it"?
3. Are there any goals you're deliberately NOT including (that someone might expect)?
4. Does anyone on the team have a different definition of success?
```

#### Step 2: Brainstorm
Generate 5–15 candidate items for the section. Label them:
```
Here are potential things to include in the Goals section:

1. Reduce checkout drop-off rate from 23% to under 15%
2. Ship to 100% of users by end of Q3
3. Zero increase in support tickets related to checkout
4. Mobile completion rate matches desktop (currently 40% lower)
5. Payment provider switch with no user-visible downtime
6. P95 checkout completion time under 3 seconds
[...]

Which of these belong? You can say "keep 1, 3, 5 — remove the rest" or just tell me what feels right.
```

#### Step 3: Curate
The user selects what stays. Accept any format:
- "Keep 1, 3, 5"
- "All of them except 4"
- "1 and 3 are good, 5 is too vague"

#### Step 4: Gap Check
After curation:
```
Anything important missing from [SECTION NAME] before I draft it?
```

#### Step 5: Draft
Write the section using only what was curated. Use `str_replace` to update the document in place — never reprint the whole doc.

#### Step 6: Refine
Iterate based on feedback. Make targeted edits. Never reprint the whole doc — only show what changed.

After 3 rounds with no substantial changes, ask:
```
This section looks stable. Anything we can cut without losing meaning?
```

---

## Stage 3 — Reader Testing

**Goal:** Catch what the author cannot see.

### Step 1: Predict reader questions
```
Before someone reads this document, what questions would they type into an AI to find it?
Let me generate the 5 most likely questions:

1. [...]
2. [...]
[...]
```

### Step 2: Test (with sub-agent if available)

Pass the document + each question to a fresh context with no prior knowledge:

```
Testing: "What is the goal of this project?"
→ Reader answer: [...]
→ Match expected: ✅ / ⚠️ Partial / ❌ Wrong

Testing: "Why was approach X rejected?"
→ Reader answer: [...]
→ Match expected: ✅ / ⚠️ Partial / ❌ Wrong
```

### Step 3: Additional checks
Run these against the document:
- "What in this doc might be ambiguous or unclear to readers?"
- "What knowledge does this doc assume readers already have?"
- "Are there any internal contradictions or inconsistencies?"

### Step 4: Fix gaps
For every ❌ or ⚠️: loop back to Stage 2 refinement for that section.

### Exit condition
When a fresh reader answers all predicted questions correctly with no ambiguity → document is ready.

---

## Document Quality Standards

### Every sentence must pass this test:
**"If I remove this sentence, does the reader lose something important?"**
If no → remove it.

### Common quality failures:

| Failure | Example | Fix |
|---|---|---|
| **Vague goals** | "Improve performance" | "Reduce P95 API latency from 800ms to under 300ms" |
| **Missing non-goals** | (nothing in non-goals section) | "We are NOT redesigning the checkout UI in this phase" |
| **Assumed context** | "As discussed in the H2 planning meeting..." | Explain the context inline |
| **Passive voice** | "A decision was made to..." | "The team decided to... because..." |
| **Weasel words** | "somewhat", "fairly", "might", "could" | Be specific or remove |
| **Missing rationale** | "We will use PostgreSQL." | "We will use PostgreSQL because we need ACID guarantees for financial data and the team has deep expertise." |
| **Orphaned alternatives** | (Alternatives Considered section is empty) | Document at least 2 alternatives and why they were rejected |

---

## PRD-Specific Template

```markdown
# PRD: [Feature Name]

**Author:** | **Date:** | **Status:** Draft
**PM:** | **Eng Lead:** | **Design:** 

---

## Problem Statement
[What user problem are we solving? Evidence that it's real.]

## Goals
- [ ] [Measurable goal 1]
- [ ] [Measurable goal 2]

## Non-Goals
- [Explicitly out of scope item 1]

## User Stories
As a [user type], I want to [action] so that [outcome].

## Requirements
### Must Have (P0)
- [Requirement]

### Should Have (P1)
- [Requirement]

### Nice to Have (P2)
- [Requirement]

## Design
[Link to Figma / mockups / wireframes]

## Technical Approach
[High-level implementation note — link to design doc for details]

## Metrics
| Metric | Baseline | Target | How measured |
|---|---|---|---|

## Timeline
| Milestone | Date | Owner |
|---|---|---|

## Risks
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|

## Open Questions
| Question | Owner | Due |
|---|---|---|

## Alternatives Considered
[What else was evaluated and why it was rejected]
```

---

## Definition of Done — Document Co-Authoring

- [ ] Stage 1 complete: meta questions answered, context dumped, understanding confirmed
- [ ] All sections drafted through the 5-step per-section workflow
- [ ] Every section curated by the author — nothing drafted without author selection
- [ ] Near-completion review done: full document read for flow, redundancy, and slop
- [ ] Stage 3 complete: reader questions predicted and tested
- [ ] All reader test failures resolved
- [ ] Every sentence earns its place — no filler, no generic statements
- [ ] All goals are measurable
- [ ] Non-goals section explicitly states scope boundary
- [ ] At least 2 alternatives considered and documented
- [ ] No orphaned "TBD" or placeholder text in final version
- [ ] Author has done a final read-through and signed off