doc

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 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

# 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"