Document

Technical Documentation Pipeline

Overview

Creates or polishes technical documentation for a project. Researches the codebase first, dispatches expert-technical-writer (opus) to write the document, then runs expert-naturalizer (opus) to remove residual AI patterns. Output lands at .mz/reports/_document_.md.

When to Use

• User asks to create docs (README, API reference, guide, tutorial, how-to, explanation)
• User asks to polish or rewrite existing documentation
• Triggers: "write docs for X", "document this module", "draft API reference", "polish the README", "create a tutorial"

When NOT to use

• User wants promotional or marketing copy — use copywrite
• User wants only an AI-text rewrite of existing prose — use naturalize
• User wants code review or audit — use review-branch or audit
• User wants to brainstorm doc structure — use brainstorm

Input

$ARGUMENTS — description of what to document. Inline modifiers:

• scope:branch|global|working — constrains codebase research to a subset (default: global)
• type:tutorial|howto|reference|explanation|readme|api|all — Diátaxis content type target (default: all lets the writer choose; explicit type produces a single-type doc)
• @doc: — existing document to polish instead of creating from scratch

If $ARGUMENTS is empty, ask via AskUserQuestion. Never guess.

Scope Parameter

See [skills/shared/scope-parameter.md](../shared/scope-parameter.md) for the canonical scope modes (branch, global, working) and their git commands.

• Default: global
• Scope constrains research only — Phase 2 writing and Phase 3 naturalization read whatever the writer needs

Constants

• TASK_DIR: .mz/task/
• REPORT_DIR: .mz/reports/
• MAXDOCTYPES: 4 (tutorial / how-to / reference / explanation per Diátaxis)

Core Process

Phase Overview

| # | Phase | File | Loop? | | --- | ------------------------------------ | -------------------- | ----------------- | | 0 | Setup | inline below | — | | 1 | Codebase research | phases/research.md | — | | 1.5 | Research approval gate | inline below | feedback sub-loop | | 2 | Writing (expert-technical-writer) | phases/writing.md | — | | 3 | Auto-naturalize (expert-naturalizer) | phases/writing.md | — |

Phase 0: Setup

1. Parse $ARGUMENTS. Extract: brief, scope:, type:, @doc: references.
2. If brief is empty → AskUserQuestion for the topic. Never guess.
3. task_name = _document_ where ` is today's date (underscores) and slug is a snake_case summary (max 20 chars). On same-day collision append v2, v3`.
4. Create .mz/task//.
5. Write state.md: schemaversion: 2, Status, Phase, Started, phasecomplete: false, what_remains: [], FilesWritten.
6. Emit a visible setup block: task_name, working dir, report path, detected modifiers.

Phase 1.5: Research Approval Gate

This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.

Pre-read: Read .mz/task//research.md with the Read tool. Capture the full file contents (stack detection, public APIs, conventions, prior art, constraints, proposed doc structure) into context.

Surface 1 — emit the plan message. Output the research verbatim as a normal markdown chat message. Emit the full verbatim contents of .mz/task//research.md — do not substitute a path, summary, or placeholder. Structure:

## Research ready for review — document

---
**Approve** → proceed to Phase 2 (writing)  ·  **Reject** → task marked aborted, no docs written  ·  reply with feedback to revise

Surface 2 — call AskUserQuestion. A short selector — do not re-embed the research contents in the question body, they live in the plan message above:

• question: The research above is ready for review.
• options: Approve — proceed to Phase 2 (writing) · Reject — abort the task, no docs written

Response handling:

• Approve → update state to research_approved, proceed to Phase 2.
• Reject → update state to aborted_by_user and stop. Do not proceed.
• Any other reply (feedback) → re-run Phase 1 with feedback, overwrite research.md, return to Surface 1, re-read research.md, and re-emit the entire plan message from scratch with the full new contents — never diff-only, never summary-only. This is a loop — repeat until the user explicitly approves. Never proceed to Phase 2 without explicit approval.

Techniques

Techniques: delegated to phase files — see Phase Overview table above.

Common Rationalizations

| Rationalization | Rebuttal | | ------------------------------------ | --------------------------------------------------- | | "skip research, just write the docs" | docs without grounding hallucinate API signatures | | "skip the approval gate" | wrong doc structure costs 3× to fix after writing | | "skip the naturalize pass" | tech-writer output still carries AI-pattern residue |

Red Flags

• You wrote the document inline instead of dispatching expert-technical-writer.
• You skipped the research approval gate.
• You skipped the naturalize pass — Phase 3 is mandatory.
• The final document mixes Diátaxis types without explicit section labels.
• You fabricated API signatures the codebase does not contain.

Verification

Output a visible final block:

Documentation pipeline complete.
Task dir:   .mz/task//
Report:     .mz/reports/_document_.md
Diátaxis:   
Naturalize: applied (, )
Files:
  - research.md
  - .md (post-naturalize)

If any phase is incomplete, print the blocker explicitly.

Error Handling

• Empty brief → AskUserQuestion. Never guess.
• @doc: path does not exist → ask the user whether to proceed without it.
• scope: resolves to zero files → escalate via AskUserQuestion; offer to widen scope.
• expert-technical-writer returns BLOCKED or NEEDS_CONTEXT → re-dispatch once with the missing context filled; if still blocked, escalate.
• expert-naturalizer returns BLOCKED → keep the technical-writer output as the final artifact and warn the user that naturalization did not run.
• Update state.md before and after every agent dispatch.

State Management

Update .mz/task//state.md after each phase:

• Status: pending | running | complete | aborted_by_user | failed
• Phase: 0 | 1 | 1.5 | 2 | 3
• FilesWritten: cumulative list

State persists to .mz/task//state.md. Schema is v2: the file's first line is schema_version: 2, and alongside the skill's existing Status / Phase / Started keys it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.

Never rely on conversation memory for cross-phase state.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

Install and usage instructions live in the source repository linked above.