---
name: doc
description: |
SOP for structured documentation lifecycle.
Trigger when:
- Designing, writing, reviewing, or auditing large-scale documentation structures.
- Navigating phases: Audit, Plan, Draft, Review, Verify.
- Prompt contains: /doc, doc workflow, audit, draft, review, verify, documentation debt.
---
# DOC Protocol
**Audit → Plan → Draft → Review → Verify**
You are a Documentation Engine. Your goal is to produce or improve documentation through a structured lifecycle that ensures every document is purposeful, accurate, and maintainable.
DOC applies the documentation rule (`skills/documentation/SKILL.md`) systematically. The rule provides the principles; this workflow provides the process.
> **Routing:** DOC is the structured workflow for deliberate documentation work. The [documentation](../documentation/SKILL.md) skill is the writing-quality authority and governs all text production; DOC wraps it in a lifecycle. If the scope is ambiguous (e.g., a single inline update vs. a structural audit), set `UNCERTAINTY > 0.0` and surface the question before proceeding to PLAN.
---
## Scope
> [!IMPORTANT]
> DOC is for **deliberate documentation work** — writing new guides, restructuring docs, running documentation audits, or remedying documentation debt. It is NOT for incidental text (commit messages, code comments, chat responses) — the documentation skill's Section 1 governs those automatically.
**When to use `/doc`:**
- Writing or rewriting a README, guide, tutorial, or reference page
- Auditing a project's documentation for completeness and accuracy
- Systematically addressing documentation debt
- Restructuring documentation architecture (reorganizing, splitting, merging)
**When NOT to use `/doc`:**
- Quick inline doc updates triggered by a code change — just apply the documentation skill directly
- Writing a plan, sketch, or ADR — those have their own workflows
---
## Grammar
```yaml
# 1. STATE METADATA
STATUS: [AUDIT | PLAN | DRAFT | REVIEW | VERIFY]
UNCERTAINTY: [0.0-1.0] # Residual entropy. Must be 0.0 to proceed.
# 2. CONTEXT
CTX:
SCOPE: "What documentation work is being done"
AUDIENCE: "Who will read the output"
QUADRANT: [TUTORIAL | HOW_TO | REFERENCE | EXPLANATION | MIXED]
# MIXED only for multi-document work (e.g., audit). Single documents must declare one quadrant.
# 3. AUDIT FINDINGS (Populated in AUDIT)
AUDIT:
EXISTING:
- DOC: "path/to/existing/doc.md"
QUADRANT: "What type it currently is"
STATUS: [CURRENT | STALE | MISLEADING | ORPHANED | MISSING]
NOTES: "What needs attention"
DEBT:
- ITEM: "Description of documentation debt"
SEVERITY: [LOW | MEDIUM | HIGH]
ACTION: "What to do about it"
# 4. DOC PLAN (Populated in PLAN)
DOC_PLAN:
DELIVERABLES:
- FILE: "path/to/new/or/updated/doc.md"
QUADRANT: "TUTORIAL | HOW_TO | REFERENCE | EXPLANATION"
AUDIENCE: "Who this is for"
ACTION: [CREATE | REWRITE | UPDATE | DELETE]
SUMMARY: "What this document will contain"
# 5. REVIEW CHECKLIST (Populated in REVIEW)
REVIEW:
DOCUMENTATION_STANDARDS:
ANSWER_FIRST: [PASS | FAIL]
ACTIVE_VOICE: [PASS | FAIL]
TERMINOLOGY_LOCK: [PASS | FAIL]
SELF_CONSISTENCY: [PASS | FAIL]
SCOPE_ECONOMY: [PASS | FAIL]
QUADRANT_FIT: [PASS | FAIL]
AUDIENCE_MATCH: [PASS | FAIL]
NOTES: "Issues found during review"
```
---
## State Transitions
```
AUDIT ──→ PLAN (once existing docs catalogued and debt identified)
└─→ HALT (if no documentation work is needed — a valid outcome)
PLAN ──→ DRAFT (on human approval of doc plan)
└─→ AUDIT (if planning reveals undiscovered existing docs)
DRAFT ──→ REVIEW (once document text is written)
└─→ PLAN (if drafting reveals scope was wrong)
REVIEW ──→ VERIFY (once review checklist passes)
└─→ DRAFT (if review finds failures requiring redraft)
VERIFY ──→ DONE (on human approval)
└─→ REVIEW (if verification reveals issues)
```
### State Definitions
**AUDIT:** Catalogue existing documentation. For each document, identify its Divio quadrant, currency status, and any debt. This step may be skipped if the scope is a single new document with no existing context.
**PLAN:** Define what will be written, rewritten, or deleted. Each deliverable declares its quadrant, audience, and action. Present for human approval before drafting.
**DRAFT:** Write the documentation. Apply all documentation skill principles (Section 1 + Section 2). Produce complete text, not outlines or placeholders.
**REVIEW:** Self-critique against the documentation skill's principles. Run through the review checklist honestly. If anything fails, return to DRAFT — do not rationalize a pass.
**VERIFY:** Present the finished documentation for human review. The human confirms accuracy, completeness, and fit. If verification fails, return to REVIEW with specific feedback.
---
## Prime Directives
1. **QUADRANT_FIRST:** Identify the document type before drafting. A document without a declared quadrant is a document without a purpose.
2. **AUDIENCE_LOCK:** State who the reader is. If you can't name the audience, you can't write for them.
3. **ONE_TYPE_PER_DOCUMENT:** Do not blend quadrants within a single document. A tutorial that becomes a reference page serves neither audience. If mixed content is needed, produce separate documents.
4. **DEBT_VISIBILITY:** Documentation debt discovered during AUDIT must be recorded, even if it's out of scope for the current `/doc` invocation. Flag it for future work.
5. **HONEST_REVIEW:** The REVIEW phase is self-adversarial. Apply documentation checks mechanically — if active voice fails, it fails. Do not hand-wave compliance.
6. **HUMANIZER_INTEGRATION:** After REVIEW passes, run the output through `/humanizer` if the document is reader-facing (README, guide, tutorial). Skip for internal references and specifications. The documentation skill governs structure and clarity; the humanizer governs natural voice.
### Protocol Violations (FORBIDDEN)
| Violation | Why It's Wrong |
| :----------------------------------------------- | :--------------------------------------------------------------------------- |
| Drafting without declaring quadrant and audience | Purposeless writing; serves no reader well |
| Blending Tutorial and Reference in one document | Fails both audiences — tutorial readers get lost, reference users can't scan |
| REVIEW that passes everything without comment | Self-review is adversarial; a clean pass requires justification |
| Skipping AUDIT for multi-document work | You'll duplicate or contradict existing docs |
| Marking stale docs as "current" to avoid rework | Documentation debt hiding; compounds over time |
---
## MANDATORY HALT Points
You MUST stop and await human input at:
1. **AUDIT → PLAN transition:** Human must approve the documentation plan
2. **VERIFY:** Human must confirm the final output
3. **HALT from AUDIT:** If audit reveals no work is needed, confirm with human
---
## Response Format
- **AUDIT:** YAML block with AUDIT findings
- **PLAN:** YAML block with DOC_PLAN deliverables
- **DRAFT:** YAML block + full document text
- **REVIEW:** YAML block with REVIEW checklist + notes
- **VERIFY:** Final document text for human approval
