Documentation Engineering

When to use

Invoke this skill to document code, write project READMEs, generate API specs, create user manuals, or co-author decision docs/proposals. This skill uses a strict, interactive co-authoring workflow to ensure the document works well when others read it.

Progressive Disclosure Rules

• Only load reference files if the user specifies a particular documentation framework (e.g., JSDoc, Docusaurus).

Standard Operating Procedure (SOP): Doc Co-Authoring Workflow

Always act as an active guide, explicitly walking the user through the following three phases sequentially. Do not rush to draft the entire document at once.

Phase 1: Context Gathering (Intent & Scoping)

Goal: Close the gap between what the user knows and what Claude knows, enabling smart guidance.

1. Initial Questions: Ask the user:
   • What type of document is this?
   • Who is the primary audience?
   • What is the desired impact when someone reads this?
   • Is there a template or specific format to follow?
2. Info Dumping: Encourage the user to dump all context (e.g., background, related discussions, technical architecture). Read shared links if integrations permit.
3. Clarification: Generate 5-10 numbered questions based on gaps in the context.
4. Exit Condition: Proceed only when you can ask about edge cases and trade-offs without needing the basics explained.

Phase 2: Refinement & Structure (Iterative Drafting)

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

1. Scaffolding: Suggest 3-5 sections appropriate for the doc type. Once agreed, create the initial document structure with placeholder text for all sections.
2. For Each Section (Chronologically):
   • Step 1 (Questions): Ask 5-10 clarifying questions about what should be included in this specific section.
   • Step 2 (Brainstorming): Brainstorm 5-20 specific things that might be included.
   • Step 3 (Curation): Ask the user which numbered points to keep, remove, or combine.
   • Step 4 (Gap Check): Ask if anything important is missing based on their selections.
   • Step 5 (SOP Drafting): Draft the section based on their exact selections.
     • Standards: Use active voice. Keep paragraphs short. All code blocks must specify a language. Use a logical header structure (H1, H2, H3).
   • Step 6 (Refining): Iteratively refine using surgical edits based on user feedback.
3. Completion Check: Read the entire document for flow, consistency, and redundancy before moving to Phase 3.

Phase 3: Reader Testing & Final Formatting

Goal: Test the document with a fresh instance (no context bleed) to verify it works for readers.

1. Predict Questions: Generate 5-10 questions that realistic readers would ask when discovering this document.
2. Testing Protocol:
   • If sub-agents are available, invoke a sub-agent with just the document content and the questions to see if it can answer them correctly.
   • If sub-agents are not available, instruct the user to open a fresh Claude conversation and test the questions.
3. Additional Checks: Check for ambiguity, false assumptions, and internal contradictions.
4. Final Deliverable: If testing reveals flaws, loop back to Phase 2 for that specific section. Otherwise, format the final approved document in Markdown or JSDoc comments.

Interaction Guidelines

• Be direct and procedural. Do not "sell" the approach—just execute the phases.
• If the user wants to skip a stage, ask if they prefer to skip the SOP and write freeform.
• Use explicit file editing operations (like str_replace) for changes. Never reprint the whole document for a one-line edit.