Doc coauthoring

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:

# [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

# 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