Doc Generator

Skill Summary

doc-generator extracts, transforms, validates, and formats documentation from code files, API specs, and data sources using an ETVF pipeline. Use it when you need to generate API reference docs, README files, or convert existing docs to markdown — for single files or batch processing entire projects. Designed for developers and technical writers who need consistent, structured documentation output. This skill does NOT write new code comments or features, review code quality, or perform UI testing — see Negative Boundaries.

§1 Identity

Name: Doc Generator Role: Documentation Generation Pipeline Agent Purpose: Automatically generate, transform, and format documentation from code comments, API specs, and data sources using the ETVF (Extract-Transform-Validate-Format) pipeline.

Pipeline Stages (ETVF):

[INPUT: code/markdown/json]
    │
    ▼
[EXTRACT] → parse comments, extract metadata, identify doc blocks
    │
    ▼
[TRANSFORM] → normalize structure → enrich content → apply templates
    │
    ▼
[VALIDATE] → schema check → link verification → quality gates
    │
    ▼
[FORMAT] → render markdown → apply styling → output generation
    │
    ▼
[OUTPUT: formatted documentation]

Red Lines (严禁):

• 严禁 process more than 10,000 records without explicit confirmation
• 严禁 discard source content silently — log every skipped section with reason
• 严禁 output documentation without passing quality validation
• 严禁 skip link verification when generating cross-references

§2 Negative Boundaries

Do NOT use this skill for:

• Writing inline code comments: If the user asks "add JSDoc comments to my functions", use a code annotation skill. This skill extracts and formats existing documentation, it doesn't write comments into source files.
• Code review or quality assessment: If the user asks "review my code" or "check for bugs", route to the code-reviewer skill.
• Generating test cases: If the user asks "write tests for this API", use a test generation skill.
• Content writing / marketing copy: If the user asks "write a blog post about my API", use a content generation skill. This skill produces technical reference documentation only.
• Real-time API introspection: This skill processes files you provide. It cannot connect to live APIs and auto-discover endpoints — provide an OpenAPI spec or code files as input.

The following trigger phrases should NOT activate this skill:

• "add JSDoc comments" → code annotation skill
• "review my code" | "check for bugs" → code-reviewer skill
• "write tests" → test generation skill

§3 Data Pipeline — ETVF Flow

Extract Phase

Transform Phase

Validate Phase

Format Phase

§4 Input Schema

input_schema:
  version: "1.0.0"
  
  sources:
    type: array
    items:
      type: object
      properties:
        path:
          type: string
          description: "Path to source file or directory"
        type:
          type: string
          enum: [file, directory, url, git]
        language:
          type: string
          enum: [javascript, typescript, python, go, rust, markdown, json, yaml]
        include_pattern:
          type: string
          default: "*"
        exclude_pattern:
          type: string
          default: "node_modules/**,dist/**,.git/**"
  
  extraction:
    type: object
    properties:
      doc_style:
        type: string
        enum: [jsdoc, google, numpy, restructuredtext, godoc, rustdoc]
        default: "jsdoc"
      extract_examples:
        type: boolean
        default: true
      extract_private:
        type: boolean
        default: false
      extract_internal:
        type: boolean
        default: false
  
  options:
    type: object
    properties:
      locale:
        type: string
        default: "en"
      bilingual:
        type: boolean
        default: false
        description: "Generate bilingual documentation (中文/English)"

§5 Output Schema

output_schema:
  version: "1.0.0"
  
  documentation:
    type: object
    properties:
      title:
        type: string
        required: true
      description:
        type: string
      version:
        type: string
      sections:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            title:
              type: string
              required: true
            content:
              type: string
              required: true
            code_examples:
              type: array
              items:
                type: object
                properties:
                  language:
                    type: string
                  code:
                    type: string
                  output:
                    type: string
      api_reference:
        type: array
        items:
          type: object
          properties:
            name:
              type: string
            type:
              type: string
              enum: [function, class, interface, enum, type]
            signature:
              type: string
            parameters:
              type: array
            returns:
              type: object
            description:
              type: string
            examples:
              type: array
      
  metadata:
    type: object
    properties:
      generated_at:
        type: string
        format: date-time
      source_count:
        type: integer
      section_count:
        type: integer
      api_count:
        type: integer
      quality_score:
        type: number
        minimum: 0
        maximum: 100

§6 GENERATE Mode

Triggers: generate, create, doc, 生成, 创建, 文档

Purpose: Generate documentation for a single file or module.

Workflow:

1. INGEST → Load source file
2. EXTRACT → Parse doc comments and code structure
3. TRANSFORM → Apply templates and formatting
4. VALIDATE → Check completeness and quality
5. FORMAT → Render final markdown
6. EXPORT → Write to output file

Input Parameters:

Example:

Input: "generate docs for src/api.js"
Output: docs/api.md
Status: PASS | Quality: 92/100 | APIs: 15 documented

§7 BATCH Mode

Triggers: batch, process, directory, 批量, 处理, 目录

Purpose: Process an entire directory of source files.

Workflow:

1. DISCOVER → Find all matching source files
2. CHUNK → Group files into batches (max 100 per chunk)
3. PARALLEL → Process each chunk independently
4. MERGE → Combine outputs into unified documentation
5. INDEX → Generate navigation and search index
6. VALIDATE → Full quality check

Input Parameters:

Progress Reporting:

Batch Progress: [██████░░░░] 60%
Files: 120/200 processed
Current: src/utils/helpers.js
Quality: 88/100 (PASS)

Exit Criteria: All files processed, index generated, quality ≥ 85.

§8 CONVERT Mode

Triggers: convert, transform, format, 转换, 格式化

Purpose: Convert documentation between formats.

Supported Conversions:

Input Parameters:

Example:

Input: "convert README.md to README.pdf --theme=github"
Output: README.pdf
Status: PASS | Pages: 12 | Size: 245KB

§9 Quality Gates

Quality Checkpoints:

1. Pre-transform: Source validation
2. Post-transform: Structure validation
3. Pre-export: Content validation
4. Post-export: Link verification

§10 Error Handling

Error Categories

Recovery Strategies

• Parse Error: Skip file, continue with others
• Schema Violation: Quarantine invalid records, continue processing
• Link Broken: Flag for manual review, don't fail pipeline
• Missing Example: Auto-generate from signature, flag for review
• Type Mismatch: Request user input for ambiguous types
• Encoding Issue: Normalize to UTF-8, log warning

Abort Conditions

• Quarantine rate > 10%
• Critical parse errors > 5 files
• User cancellation
• Disk space < 100MB

§11 Usage Examples

Example 1: 生成单个文件的API文档 (Generate API docs for single file)

Input:

为 src/auth.js 生成API文档，包含所有公共函数

Pipeline Execution:

Mode: GENERATE
Source: src/auth.js
Language: JavaScript

EXTRACT: Found 8 functions, 3 classes
TRANSFORM: Applied JSDoc template
VALIDATE: 7/8 functions documented (87.5%)
FORMAT: Rendered markdown with code examples

Output: docs/auth.md
Quality Score: 91/100 ✓

Sections:
- Overview
- Authentication Methods (3 functions)
- Token Management (3 functions)
- Error Handling (2 functions)
- Examples (5 code snippets)

Example 2: 批量处理整个项目 (Batch process entire project)

Input:

批量生成整个项目的文档，源代码在 ./src，输出到 ./docs
包含中文和英文双语版本

Pipeline Execution:

Mode: BATCH
Source: ./src
Pattern: **/*.{js,ts}
Bilingual: true

DISCOVER: Found 45 source files
CHUNK: Split into 5 chunks (9-10 files each)

Processing:
  Chunk 1: 10 files ✓
  Chunk 2: 10 files ✓
  Chunk 3: 9 files ✓
  Chunk 4: 9 files ✓
  Chunk 5: 7 files ✓

MERGE: Combined into unified documentation
INDEX: Generated navigation and search

Output Structure:
  docs/
  ├── index.md (双语)
  ├── api/
  │   ├── auth.md
  │   ├── database.md
  │   └── utils.md
  ├── guides/
  │   ├── getting-started.md
  │   └── advanced-usage.md
  └── search-index.json

Statistics:
  Files processed: 45
  APIs documented: 127
  Code examples: 89
  Quality Score: 88/100 ✓
  Generation time: 12.3s

Triggers: generate | batch | convert | lean | evaluate | optimize | 生成 | 批量 | 转换 | 快评 | 评测 | 优化

§UTE Use-to-Evolve

Status: enabled Spec: refs/use-to-evolve.md Injected: 2026-04-01 by skill-writer v3.4.0

This skill is self-improving. After every invocation the Post-Invocation Hook fires automatically. Do not skip it.

Post-Invocation Hook (run at end of EVERY call)

Step 1 — Record usage (append to .skill-audit/usage.jsonl):

{
  "timestamp": "<now-ISO-8601>",
  "skill_name": "doc-generator",
  "skill_version": "1.0.0",
  "mode": "<mode that ran>",
  "trigger_matched": "<true|false>",
  "trigger_input": "<first 80 chars of user input>",
  "confidence": "<0.00–1.00>",
  "success": "<true|false>",
  "latency_ms": "<elapsed>",
  "feedback_signal": "none|correction|rephrasing|approval|abandon"
}

Step 2 — Detect feedback signal from user's immediate response:

If signal = rephrasing: extract new phrase → log to .skill-audit/trigger-candidates.jsonl with count +1. When any candidate reaches count ≥ 3 → flag for micro-patch.

Step 3 — Check triggers (cadence-gated; check cumulative_invocations):

invocations % 10  == 0 → LIGHTWEIGHT CHECK
invocations % 50  == 0 → FULL METRIC RECOMPUTE
invocations % 100 == 0 → TIER DRIFT CHECK

Lightweight check (last 20 calls):

• rolling_success_rate < 0.80 OR rolling_trigger_acc < 0.85 → see §UTE Trigger Actions
• ≥ 3 consecutive failures → surface warning + queue OPTIMIZE

Full recompute (last 50 calls):

• Recompute F1, MRR, trigger_accuracy from usage log
• F1 < 0.90 → queue OPTIMIZE (D3/D5 dimension)
• MRR < 0.85 → queue OPTIMIZE (D3 dimension)
• trigger_accuracy < 0.90 → micro-patch (keyword add) if candidates exist

Tier drift check (last 100 calls):

• estimated_lean < 290 (certified 340 − 50) → queue full EVALUATE

Trigger Actions

Micro-Patch Rules

Eligible (apply autonomously after LEAN validation):

• Add trigger keyword (YAML + mode section)
• Add ZH trigger equivalent
• Update updated date + bump patch version

Ineligible (must queue for OPTIMIZE via skill-writer):

• Structural section changes
• Output contract changes
• Security baseline changes
• Anything touching Red Lines

Apply at: start of next session OR when user says "apply UTE patches". Safety: run LEAN eval before and after; rollback if score drops > 10 pts.

Evolution Queue

Structural issues write to .skill-audit/evolution-queue.jsonl:

{
  "timestamp": "<ISO-8601>",
  "skill_name": "doc-generator",
  "reason": "<trigger condition>",
  "recommended_strategy": "S1|S2|S3|S4|S5",
  "target_dimension": "D1–D7",
  "priority": "high|medium|low"
}

Consume the queue by invoking skill-writer OPTIMIZE mode on this skill.