main

name: doc-coauthoring description: Guide users through structured co-authoring of documentation, proposals, specs, and written artifacts. USE WHEN user wants to write a design doc, RFC, proposal, technical spec, KEP, enhancement proposal, or co-author documentation.

Doc Co-Authoring

Turn incomplete context into a clear document through an interactive, structured workflow. Emphasis on concise, idiomatic English and incremental validation.

When To Use

  • Write a design doc, RFC, proposal, PRD, decision record, or technical spec
  • Restructure or refine an existing document
  • Copyedit a draft for grammar, clarity, or natural English
  • Rewrite awkward or non-native phrasing
  • Gather context and turn it into a coherent written artifact
  • Red Hat-specific: KEP, enhancement proposals, release notes

Do not force this workflow. If the user wants freeform help, use a lighter touch.

Workflow

1. Align on the Document

Ask for minimum context needed:

  • Document type and template (if any)
  • Primary audience
  • Desired outcome from readers
  • Deadlines, approvals, or constraints

If a draft already exists, read it before asking questions.

2. Gather Context

Accept context in any form: rough info dump, links, notes, constraints, tradeoffs, rejected alternatives. Then ask focused follow-up questions to close the biggest gaps. Prefer a small number of high-value questions over a long interview.

3. Agree on Structure

  • Identify target sections
  • Suggest structure if user doesn’t have one
  • Start with the section containing the main decision or the most unknowns

4. Draft Section by Section

For each section:

  1. Ask a few clarifying questions specific to that section
  2. Brainstorm candidate points
  3. Ask what to keep, combine, or drop
  4. Draft the section
  5. Refine based on targeted feedback

Prefer surgical edits and short iteration loops. Avoid rewriting the entire document when only one section needs work.

5. Review the Full Document

Reread and check for:

  • Gaps in logic
  • Duplicated content
  • Contradictions between sections
  • Generic filler that can be removed
  • Missing context readers actually need

6. Reader Test

Pressure-test from a new reader’s perspective:

  • List key questions a reader should be able to answer after reading
  • Check whether the draft answers them clearly
  • Identify hidden assumptions, undefined terms, ambiguous statements

Language Pass

When improving English:

  • Rewrite awkward or literal phrasing into natural English
  • Prefer short, direct sentences over long or tangled ones
  • Use active voice unless passive is clearer
  • Fix articles, tense, agreement, punctuation, parallel structure
  • Remove redundancy, filler, repeated words
  • Keep terminology consistent

Examples:

  • ❌ “This feature allows to users configure the runner easily.”
  • ✅ “This feature lets users configure the runner easily.”
  • ❌ “We made this change for avoid failures during deploy.”
  • ✅ “We made this change to avoid deployment failures.”

Editing Guidelines

When making direct edits:

  • Fix clarity, grammar, and natural English first
  • Keep the existing voice unless asked to change tone
  • Preserve useful content, tighten weak content
  • Prefer concrete examples over abstract filler
  • Avoid making policy decisions the user hasn’t made
  • Brainstorming: For exploring ideas and approaches before writing
  • WritingPlans: For implementation plans (code-focused, not doc-focused)