Cco Docs

/cco-docs

Documentation Gap Analysis — Identify missing docs, generate what's needed.

Output Constraints

Every sentence earns its place. Show > tell, examples > prose. Headers/bullets/tables for scanning. Copy-pasteable commands. Avoid: filler, marketing language, obvious statements, duplicate content.

Args

| Flag | Effect | |------|--------| | --auto | Detect, analyze, generate all missing docs | | --preview | Analyze gaps only, no generation | | --scope=X | Single scope: readme, api, dev, user, ops, changelog, refine, verify | | --update | Regenerate even if docs exist | | --force-approve | Auto-apply needs_approval items (architectural changes). Combines with --auto. |

State Management

Per CCO Rules: State Management. This skill uses task prefix [DOC].

| Task | Created | Completed | |------|---------|-----------| | [DOC] Analysis | Phase 2 start | Phase 2 end | | [DOC] Gap | Phase 3 start | Phase 3 end | | [DOC] Generate | Phase 5 start | Phase 5 end | | [DOC] Summary | Phase 6 start | Phase 6 end |

Recovery: At Phase 1 start, run TaskList. If [DOC] tasks exist with incomplete status → per State Management recovery protocol.

Context

• Git status: !git status --short --branch
• Args: $ARGUMENTS

Scopes

| Scope | Target | Purpose | |-------|--------|---------| | readme | README.md | Project overview, quick start | | api | docs/api/, API.md | Endpoint/function reference | | dev | CONTRIBUTING.md, docs/dev/ | Developer onboarding | | user | docs/user/, USAGE.md | End-user guides | | ops | docs/ops/, DEPLOY.md | Deployment, operations | | changelog | CHANGELOG.md | Version history | | refine | Existing docs | UX/DX quality improvement | | verify | Existing docs | Verify claims against source code |

Execution Flow

Setup → Analysis → Gap Analysis → [Plan] → Generate → Summary

Phase 1: Setup [SKIP if --auto]

Pre-flight: Verify git repo: git rev-parse --git-dir 2>/dev/null → not a repo: warn "Not a git repo — git context unavailable" and continue (git optional for docs).

Recovery check: TaskList → filter [DOC] prefix. If incomplete tasks found → per State Management recovery protocol.

AskUserQuestion([
  {
    question: "Which documentation areas should be covered?",
    header: "Areas",
    options: [
      { label: "Core (Recommended)", description: "readme + changelog" },
      { label: "Technical (Recommended)", description: "api + dev" },
      { label: "User-facing", description: "user + ops" }
    ],
    multiSelect: true
  },
  {
    question: "How should existing docs be handled?",
    header: "Mode",
    options: [
      { label: "Fill Gaps (Recommended)", description: "Only create what's missing" },
      { label: "Refine existing", description: "Improve quality of current docs" },
      { label: "Verify claims", description: "Check doc claims against source code" },
      { label: "Update All", description: "Regenerate even if docs exist" }
    ],
    multiSelect: false
  }
])

In --auto: generation scopes only (refine/verify require explicit --scope=).

Phase 2: Analysis

TaskCreate [DOC] Analysis (status: in_progress).

Delegate to cco-agent-analyze (scopes: [doc-sync], mode: auto): scan existing docs, detect project type, detect documentation needs. Per CCO Rules: Agent Contract — validate agent JSON output, retry once on malformed response, on second failure continue with remaining groups, score failed dimensions as N/A. Fallback: file existence checks.

TaskUpdate [DOC] Analysis → completed. Write gap findings to description in compact format.

Phase 3: Gap Analysis [IDEAL vs CURRENT]

TaskCreate [DOC] Gap (status: in_progress).

Ideal docs by project type (Per CCO Rules: Project Types):

| Type | README | API | Dev | User | Ops | Changelog | |------|--------|-----|-----|------|-----|-----------| | cli | Full | - | Basic | Full (man/help) | - | Yes | | library | Full | Full | Full | Guides | Publish | Yes | | api | Full | Full | Full | Full | Full | Yes | | web | Full | Components | Full | Basic | Full | Yes | | mobile | Full | - | Full | Store listing | Full | Yes | | desktop | Full | - | Full | Full | Full | Yes | | monorepo | Full | Per-package | Full | Per-package | Full | Yes | | iac | Full | - | Full | Runbook | Full | Yes | | devtool | Full | Full | Full | Full | - | Yes | | data | Full | Schema | Full | Pipeline guide | Full | Yes | | ml | Full | Model card | Full | Inference guide | Full | Yes | | embedded | Full | HW interface | Full | Setup guide | Flash guide | Yes | | game | Full | - | Full | Player guide | - | Yes | | extension | Full | API/hooks | Full | Marketplace | Publish | Yes |

Missing docs = HIGH, incomplete (<70%) = MEDIUM.

Refine scope: Analyze for scannability, clarity, redundancy, conciseness. Convert to improvement tasks.

Verify scope: Cross-reference doc claims against source. Testable claims checklist: CLI flags, config keys, file paths, function signatures, step counts, default values, env vars. For each: Grep/Read source to confirm. Minimum: ALL numbered lists, ALL code examples, ALL flag tables. Mismatches → fix tasks.

Phase 4: Plan Review [CONDITIONAL, SKIP if --auto]

Display plan (target files, sections, sources). Ask: Generate All (recommended) / High Priority Only / Abort.

Phase 5: Generate Documentation [SKIP if --preview]

TaskUpdate [DOC] Gap → completed. TaskCreate [DOC] Generate (status: in_progress).

Recovery-aware read: If gap analysis results not in conversation context (compaction occurred), reconstruct from TaskGet on [DOC] Analysis and [DOC] Gap task descriptions.

Delegate to cco-agent-apply (scope: docs, operations: [{action, scope, file, sections, sources, projectType}]). Extract from actual source files. Apply: brevity, examples, scannability, actionability. Avoid: filler, "this document explains...", long paragraphs. On error: count as failed, continue.

Source mandate: Every documented flag, endpoint, or config value MUST have Grep/Read verification before inclusion. Never document features from memory or inference.

Phase 6: Summary

State cleanup: TaskUpdate all [DOC] tasks → completed. TaskCreate [DOC] Summary with final accounting in description.

Per CCO Rules: Accounting.

Interactive output format:

cco-docs complete
=================
| Scope     | Status   | File            | Lines |
|-----------|----------|-----------------|-------|
| readme    | Updated  | README.md       |   +12 |
| api       | Created  | docs/api.md     |    85 |
| dev       | Skipped  | CONTRIBUTING.md |     — |

Applied: 2 | Failed: 0 | Needs Approval: 0 | Total: 2

Gap summary (before/after), files generated, applied/failed/needs_approval/total.

--auto: cco-docs: {OK|WARN|FAIL} | Applied: N | Failed: N | Needs Approval: N | Total: N

Source & license

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

• Author: sungurerdim
• Source: sungurerdim/ClaudeCodeOptimizer
• License: MIT
• Homepage: https://github.com/sungurerdim/ClaudeCodeOptimizer#install

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