doc-coauthoring

name

doc-coauthoring

description

Guide users through a structured 3-stage workflow for co-authoring documentation within sea-domain-forge. Use when the user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. Integrates with conversation-to-spec for SEA specification compliance and cognitive-artifacts for interactive completeness validation. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

Doc Co-Authoring Workflow

A structured 3-stage workflow for collaborative document creation. Act as an active guide, walking users through: Context Gathering → Refinement & Structure → Reader Testing.

When to Offer This Workflow

Trigger conditions:

• User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
• User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
• User seems to be starting a substantial writing task

Initial offer:

Offer the structured workflow and explain the three stages:

1. Context Gathering — User provides all relevant context while you ask clarifying questions
2. Refinement & Structure — Iteratively build each section through brainstorming and editing
3. Reader Testing — Test the doc with a fresh agent instance to catch blind spots

Ask if they want this workflow or prefer to work freeform. If they decline, work freeform.

Stage 1: Context Gathering

Goal: Close the gap between what the user knows and what the AI knows.

Initial Questions

1. What type of document is this? (e.g., technical spec, decision doc, proposal)
2. Who's the primary audience?
3. What's the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

If user provides a template or existing document: Read it before asking further questions.

If user mentions a shared document: Use available integrations to fetch it. Check for images without alt-text and offer to generate alt-text for AI accessibility.

Info Dumping

Encourage the user to dump all context they have. Request:

• Background on the project/problem
• Related team discussions or shared documents
• Why alternative solutions aren't being used
• Organizational context (team dynamics, past incidents, politics)
• Timeline pressures or constraints
• Technical architecture or dependencies
• Stakeholder concerns

Advise them not to worry about organizing it — just get it all out.

Clarifying Questions

After the initial dump, generate 5–10 numbered questions based on gaps:

Inform them they can use shorthand (e.g., "1: yes, 2: see that doc, 3: no due to compat"), or keep info-dumping. Whatever is most efficient.

Exit condition: Sufficient context when questions address edge cases and trade-offs, not basics.

---

Stage 2: Refinement & Structure

Goal: Build the document section by section through brainstorming, curation, and iterative refinement.

Instructions to user:

• The document is built section by section
• For each section: clarifying questions → brainstorm → curate → draft → refine

Section Ordering

Start with the section that has the most unknowns:

• Decision docs → core proposal
• Technical specs → technical approach
• Leave summary sections for last

Document Scaffold

Create an initial document with all section headers and placeholder text ([To be written]). Create this as a file in the working directory. Confirm the filename and indicate it's time to fill in each section.

For Each Section

Step 1: Clarifying Questions

Ask 5–10 specific questions about what to include in this section.

Step 2: Brainstorming

Brainstorm 5–20 options for what to include. Look for:

• Context shared earlier that might have been forgotten
• Angles or considerations not yet mentioned

Step 3: Curation

Ask which points to keep, remove, or combine. Request brief justifications:

• "Keep 1, 4, 7, 9"
• "Remove 3 (duplicates 1)"
• "Combine 11 and 12"

If user gives freeform feedback, parse their preferences and apply.

Step 4: Gap Check

Based on what they've selected, ask if anything important is missing.

Step 5: Drafting

Replace the placeholder text for this section with the drafted content using str_replace (never reprint the whole document). Ask them to read through and indicate what to change.

Key instruction to user (include when drafting the first section):

"Instead of editing the doc directly, please tell me what to change. This helps me learn your style for future sections. For example: 'Remove the X bullet — already covered by Y' or 'Make the third paragraph more concise'."

Step 6: Iterative Refinement

Use str_replace for all edits. After 3 consecutive iterations with no substantial changes, ask if anything can be removed without losing important information.

When the section is done, confirm completion and ask if ready to move to the next section.

Near Completion Check

At 80%+ sections done, re-read the entire document and check for:

• Flow and consistency across sections
• Redundancy or contradictions
• Anything that feels like generic filler
• Whether every sentence carries weight

---

Stage 3: Reader Testing

Goal: Test the document with a fresh agent (no context bleed) to catch blind spots.

Step 1: Predict Reader Questions

Generate 5–10 questions readers would realistically ask when trying to discover or understand this document.

Step 2: Test with Sub-Agent (if available)

For each question, invoke a sub-agent with just the document content and the question. Summarize what the reader agent got right/wrong for each question.

If no sub-agent access: Provide the user with instructions to open a fresh conversation, paste the document, and ask the generated questions. Ask for the reader agent's responses so gaps can be fixed.

Step 3: Additional Checks

Ask a sub-agent (or the user, in the manual case):

• "What in this doc might be ambiguous or unclear to readers?"
• "What knowledge does this doc assume readers already have?"
• "Are there internal contradictions or inconsistencies?"

Step 4: Fix Gaps

If issues are found, loop back to Stage 2 refinement for the problematic sections.

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

---

Final Review

When reader testing passes:

1. Recommend a final read-through by the user — they own the document
2. Suggest double-checking any facts, links, or technical details
3. Ask them to verify it achieves the impact they wanted

Final tips:

• Consider linking this conversation in an appendix so readers can see how the doc was developed
• Use appendices to provide depth without bloating the main doc
• Update the doc as feedback arrives from real readers

SEA Specification Integration

When the document is a SEA specification (ADR/PRD/SDS):

• Coordinate with conversation-to-spec Phase 3 for proper spec format compliance
• Verify traceability chain: ADR → PRD → SDS → SEA-DSL
• After drafting, offer to generate a CADSL checklist (via cognitive-artifacts) to validate completeness of all required sections

Tips for Effective Guidance

Tone: Direct and procedural. Explain rationale briefly only when it affects user behavior.

Handling Deviations:

• User wants to skip a stage → ask if they want to work freeform
• User seems frustrated → acknowledge and offer a faster path

Context Management:

• Proactively ask about gaps as they appear — don't let them accumulate

Quality over Speed:

• Don't rush through stages; each iteration should make meaningful improvements