Doc Coauthoring

Doc Co-Authoring Workflow

Three-stage workflow: Context Gathering → Refinement & Structure → Reader Testing.

Offer the workflow when user starts a writing task. If declined, work freeform.

Stage 1: Context Gathering

Goal: Close the knowledge gap so you can guide effectively later.

Initial Questions

Ask for meta-context:

1. Document type (technical spec, decision doc, proposal, etc.)
2. Primary audience
3. Desired impact on the reader
4. Template or format requirements
5. Other constraints

Accept shorthand answers or info dumps.

If a template or existing doc is provided, read it. For docs with images lacking alt-text, offer to generate alt-text — images are invisible to future AI readers.

Context Dump

Encourage the user to share everything relevant:

• Project/problem background
• Related discussions or documents
• Why alternatives were rejected
• Organizational context, timeline, dependencies, stakeholder concerns

Offer to pull context via available integrations (Slack, Drive, etc.). If none available, suggest enabling connectors or pasting content directly.

Clarifying Questions

After the initial dump, generate 5–10 numbered questions targeting gaps.

Let users answer in shorthand (e.g., "1: yes, 2: see #channel, 3: no").

Track what's learned vs. what's still unclear. Address gaps immediately.

Exit condition: Questions show understanding of edge cases and trade-offs without needing basics explained.

Transition: ask if there's more to add, or if it's time to draft.

Stage 2: Refinement & Structure

Goal: Build the document section by section through brainstorm → curate → draft → refine.

Per-section process:

1. Clarifying questions about what to include
2. Brainstorm 5–20 options
3. User curates (keep/remove/combine)
4. Draft the section
5. Refine through surgical edits

Establish Structure

Before proposing sections, apply the reader contract and answer-first rule from jaw-dev/references/reader-documents.md (READER-DOC-01/02). Stage 3 below remains the canonical reader test for co-authored documents.

If structure is clear: ask which section to start with. Suggest starting with the most uncertain section.

If structure is unclear: propose 3–5 sections based on doc type and adjust per feedback.

Create the scaffold (artifact or markdown file) with section headers and [To be written] placeholders.

Per-Section Workflow

1. Clarifying Questions

Ask 5–10 questions specific to the section's purpose.

2. Brainstorming

Generate 5–20 numbered options. Surface forgotten context and unconsidered angles. Offer to brainstorm more.

3. Curation

Ask which points to keep, remove, or combine. Accept numbered or freeform feedback — parse preferences and apply.

4. Gap Check

Ask if anything important is missing.

5. Drafting

Replace placeholder with drafted content using str_replace.

On the first section, instruct: "Tell me what to change instead of editing directly — this helps me learn your style for later sections."

6. Iterative Refinement

• Use str_replace for edits — never reprint the whole doc
• If user edits directly, note their preferences for future sections
• After 3 iterations with no substantial changes, ask what can be removed
• Continue until user is satisfied

Near Completion

At 80%+ sections done, re-read the full document checking for:

• Flow and consistency across sections
• Redundancy or contradictions
• Generic filler — every sentence should carry weight

Provide feedback, then ask if ready for Reader Testing.

Stage 3: Reader Testing

Goal: Test the document with a context-free reader to catch blind spots.

Step 1: Predict Reader Questions

Generate 5–10 questions readers would realistically ask when discovering this document.

Step 2: Test

With sub-agents: For each question, invoke a sub-agent with only the document and the question (no conversation context). Summarize what it got right/wrong.

Without sub-agents: Instruct user to open a fresh conversation, paste the doc, and ask the generated questions. Have the reader report: answer, ambiguities, assumed knowledge.

Step 3: Additional Checks

Check (via sub-agent or fresh conversation) for:

• Ambiguity or unclear phrasing
• Assumed reader knowledge
• Internal contradictions

Step 4: Fix

If issues found, loop back to Stage 2 refinement for affected sections.

Exit condition: Reader consistently answers questions correctly with no new gaps.

Final Review

When reader testing passes:

1. Recommend a personal read-through — user owns the document's quality
2. Suggest verifying facts, links, and technical details
3. Ask if it achieves the intended impact

Tips: link this conversation in an appendix, use appendices for depth, update as real reader feedback arrives.