Ref Documentation

CUI Documentation Skill

Standards and workflows for writing clear, maintainable technical documentation in CUI projects.

Note: This skill covers general documentation. For code documentation, use:

• pm-dev-java:javadoc for Java code documentation
• cui-frontend-development/jsdoc-standards.md for JavaScript documentation

Available Workflows

This skill provides nine specialized workflows:

Workflow: format-document

Auto-fix common AsciiDoc formatting issues with safety features.

What It Fixes

• Add blank lines before lists
• Convert deprecated <<>> syntax to xref:
• Fix header attributes
• Remove trailing whitespace

Parameters

• target (required): File path or directory path
• fix_types (optional, default: "all"): Types of fixes: "lists", "xref", "headers", "whitespace", "all"

Steps

Step 1: Load Documentation Standards

Read references/asciidoc-formatting.md

Step 2: Discover Files

If target is a file:

• Verify file exists and has .adoc extension

If target is a directory:

• Use Glob: {directory}/*.adoc (non-recursive)
• Filter out target/ directories

Step 3: Run Auto-Formatter

Build command with options:

OPTIONS=""
if [fix_types != "all"]; then OPTIONS="$OPTIONS -t {fix_type}"; fi

python3 .plan/execute-script.py pm-documents:ref-documentation:docs format $OPTIONS {target}

Step 4: Parse Output

Extract statistics:

• Files processed
• Files modified
• Issues fixed
• Fix details per file

Step 5: Report Results

Format Fixes Applied to {target}
Files modified: {count}
Issues fixed: {count}
Changes applied: {list}

Step 6: Validation (after changes applied)

Run validation:

python3 .plan/execute-script.py pm-documents:ref-documentation:docs validate {target}

Workflow: validate-format

Validate AsciiDoc files for format compliance.

What It Checks

• Section headers with blank lines
• Proper list formatting
• Blank lines before/after lists
• Code block formatting

Parameters

• target (required): File path or directory path
• apply_fixes (optional, default: false): Apply automatic fixes

Steps

Step 1: Load Documentation Standards

Read references/asciidoc-formatting.md

Step 2: Discover Files

If target is a file:

• Verify file exists and has .adoc extension

If target is a directory:

• Use Glob: {directory}/*.adoc (non-recursive)

Step 3: Run Format Validation

python3 .plan/execute-script.py pm-documents:ref-documentation:docs validate {target}

Step 4: Parse Output

Extract warnings matching Line [0-9]+:

• Categorize issues by type
• Track by file and line number

Step 5: Apply Fixes (if requested)

If apply_fixes=true:

• For each issue, read file context (±5 lines)
• Use Edit tool to fix the issue
• Track fixes applied

Step 6: Re-Validate (if fixes applied)

Re-run validator and compare:

• Before: {total_issues}
• After: {remaining_issues}
• Fixed: {fixed_count}

Step 7: Generate Report

## AsciiDoc Format Validation Complete

**Status**: ✅ PASS | ⚠️ WARNINGS | ❌ FAILURES

**Summary**: Validated {file_count} file(s)

**Metrics**:
- Files validated: {count}
- Format issues found: {count}
- Issues fixed: {count}
- Issues remaining: {count}

**Issues by Category**:
- Blank line after header: {count}
- Blank line before list: {count}
- Other format violations: {count}

**Details by File**:
### {file_1}
- Line {N}: {issue description}
- Status: ✅ Clean | ⚠️ Issues remaining

Workflow: verify-links

Verify all links and cross-references in AsciiDoc files.

What It Verifies

• Cross-reference file links (xref:)
• Internal anchor references (<>)
• Link formats and syntax

Parameters

• target (required): File path or directory path
• fix_links (optional, default: false): Fix broken links

Steps

Step 1: Load Documentation Standards

Read references/asciidoc-formatting.md

Step 2: Discover Files

If target is a file:

• Verify file exists and has .adoc extension

If target is a directory:

• Use Glob: {directory}/*.adoc (non-recursive)

Step 3: Setup Report Directory

mkdir -p target/asciidoc-link-verifier

Step 4: Run Link Verification

python3 .plan/execute-script.py pm-documents:ref-documentation:docs verify-links --file {file_path} --report target/asciidoc-link-verifier/links.md

For directories:

python3 .plan/execute-script.py pm-documents:ref-documentation:docs verify-links --directory {directory} --report target/asciidoc-link-verifier/links.md

Step 5: Parse Report

Read target/asciidoc-link-verifier/links.md and extract:

• Broken file links
• Broken anchors
• Format violations

Step 6: Manual Verification (CRITICAL)

For each "broken" link reported:

1. Extract target path
2. Resolve absolute path: realpath {relative_target_path}
3. Verify with Read tool
4. If file EXISTS but script reported broken: Report false positive
5. If file NOT FOUND: Confirm broken

Step 7: Fix Internal Anchors (if approved)

For missing anchors:

1. Search for matching section header
2. Add anchor ID: [#anchor-id] before header
3. Use Edit tool

Step 8: Generate Report

## AsciiDoc Link Verification Complete

**Status**: ✅ PASS | ⚠️ WARNINGS | ❌ FAILURES

**Summary**: Verified links in {file_count} file(s)

**Metrics**:
- Files verified: {count}
- Broken file links: {count}
- Broken anchors: {count}
- Issues fixed: {count}

**Details by File**:
### {file_1}
- Line {N}: xref to {target} - {status}
- Line {N}: anchor <<{id}>> - {status}

Workflow: review-content

Review AsciiDoc content for quality: correctness, clarity, tone, style, and completeness.

What It Reviews

• Correctness: Factual claims, RFC citations, verifiable statements
• Clarity: Concise, unambiguous, clear explanations
• Tone & Style: Professional, technical, no marketing language
• Consistency: Terminology, formatting patterns
• Completeness: No missing sections, TODOs, or gaps

Parameters

• target (required): File path or directory path
• apply_fixes (optional, default: false): Apply content fixes

Steps

Step 1: Load Documentation Standards

Read references/tone-and-style.md Read references/documentation-core.md

Step 2: Discover Files

If target is a file:

• Verify file exists and has .adoc extension

If target is a directory:

• Use Glob: {directory}/*.adoc (non-recursive)

Step 3: Run Content Analysis

python3 .plan/execute-script.py pm-documents:ref-documentation:docs review --file {file_path}

For directories:

python3 .plan/execute-script.py pm-documents:ref-documentation:docs review --directory {directory}

Step 4: Parse JSON Output

Script returns structured JSON:

{
  "status": "success",
  "data": {
    "files_analyzed": N,
    "average_quality_score": N,
    "issues": [
      {
        "file": "path",
        "line": N,
        "type": "tone|correctness|completeness",
        "severity": "critical|high|medium|low",
        "message": "description"
      }
    ]
  }
}

Step 5: Apply Deep Analysis

For each issue from script, apply Claude judgment:

• Is the marketing language truly promotional or factual?
• Can claims be verified from context?
• Are TODOs appropriate (e.g., in development docs)?

Step 6: Categorize by Priority

Priority 1 - CRITICAL:

• Unverified factual claims
• Marketing/promotional language
• Transitional markers in specification docs

Priority 2 - HIGH:

• Clarity problems
• Tone issues
• Consistency violations

Priority 3 - MEDIUM:

• Minor wording improvements

Step 7: Apply Fixes (if requested)

If apply_fixes=true:

• For Priority 1 and 2 issues
• Read file context
• Use Edit tool for fixes
• Ask user before major changes

Step 8: Generate Report

## AsciiDoc Content Review Complete

**Status**: ✅ PASS | ⚠️ WARNINGS | ❌ FAILURES

**Summary**: Reviewed {file_count} file(s)

**Quality Score**: {average_score}/100

**Metrics**:
- Files reviewed: {count}
- Tone issues: {count}
- Correctness issues: {count}
- Completeness issues: {count}

**Issues by Priority**:
- CRITICAL: {count}
- HIGH: {count}
- MEDIUM: {count}

**Details by File**:
### {file_1}

**Tone Issues:**
- Line {N}: {description}
  - Current: "{text}"
  - Suggested: "{improved}"

**Correctness Issues:**
- Line {N}: {description}

**Completeness Issues:**
- Line {N}: {description}

Workflow: comprehensive-review

Orchestrate all review workflows for thorough documentation quality assurance.

What It Does

Runs three phases in sequence with intelligent failure handling:

1. Format Validation (fail-fast on errors)
2. Link Verification (continue regardless)
3. Content Quality Review (continue regardless)

Provides consolidated report with aggregated results.

Parameters

• target (required): File path or directory path
• stop_on_error (optional, default: true): Stop on format errors (Phase 1 failure)
• apply_fixes (optional, default: false): Attempt auto-fixes in all phases
• skip_content (optional, default: false): Skip Phase 3 (content review)

Steps

Step 1: Load Documentation Standards

Read workflows/review-orchestration.md Read workflows/link-verification.md Read workflows/content-review.md

Step 2: Discover Files

If target is a file:

• Verify file exists and has .adoc extension

If target is a directory:

• Use Glob: {directory}/*.adoc (non-recursive)
• Filter out target/ directories

Step 3: Phase 1 - Format Validation

Execute validate-format workflow:

Parameters:
  target: {target}
  apply_fixes: {apply_fixes}

Parse results:

• Extract format issues count
• Store format status (PASS/WARNINGS/FAILURES)

Decision Point:

If format FAILURES found AND stop_on_error=true:

• STOP - Skip Phase 2 and 3
• Generate partial report (format only)
• Message: "Format validation FAILED. Fix errors before link/content review."

Otherwise:

• CONTINUE to Phase 2

Step 4: Phase 2 - Link Verification

Execute verify-links workflow:

Parameters:
  target: {target}
  fix_links: {apply_fixes}

Enhanced Link Verification:

After running verify-adoc-links.py, classify results:

python3 .plan/execute-script.py pm-documents:ref-documentation:docs classify-links --input target/links.json --output target/classified.json

Parse classified results:

• likely-false-positive: Keep links (report for info)
• must-verify-manual: Use Read tool to verify each
• definitely-broken: Ask user before removal

Manual Verification (link-verification-protocol.md):

For each must-verify-manual link:

1. Extract target path from xref
2. Resolve absolute path: realpath {path}
3. Verify with Read tool
4. If EXISTS: Keep link (report false positive)
5. If NOT FOUND: Ask user before removal

Store link results:

• Broken links count
• False positives count
• Manual verification outcomes

CONTINUE to Phase 3 (regardless of link results)

Step 5: Phase 3 - Content Quality Review

Skip if skip_content=true

Execute review-content workflow with ULTRATHINK:

Parameters:
  target: {target}
  apply_fixes: {apply_fixes}

Enhanced Content Analysis:

python3 .plan/execute-script.py pm-documents:ref-documentation:docs analyze-tone --file {file_path} --output target/tone-analysis.json

Parse tone analysis JSON:

• promotional: Marketing/buzzword language
• performance_claim: Performance assertions requiring data
• standards_claim: Standards/compatibility claims requiring citations
• missing_sources: Claims without attribution

ULTRATHINK Analysis (content-review-framework.md):

For each flagged promotional phrase:

1. Apply decision framework:
   • Does this describe verifiable, specific capability? → Factual
   • Can this be measured or tested? → Factual
   • Does it compare favorably without evidence? → Promotional
2. Generate finding with reasoning
3. Suggest factual alternative

Store content results:

• Promotional language count
• Unverified claims count
• Missing sources count
• ULTRATHINK findings

Step 6: Aggregate Results

Combine all phase results:

Total files: {count}
Phase 1 (Format): {PASS|WARNINGS|FAILURES} - {issue_count} issues
Phase 2 (Links): {PASS|WARNINGS|FAILURES} - {issue_count} issues
Phase 3 (Content): {PASS|WARNINGS|FAILURES} - {issue_count} issues

Overall status:

• ✅ PASS: All phases passed
• ⚠️ WARNINGS: Some non-critical issues
• ❌ FAILURES: Critical issues found

Step 7: Generate Consolidated Report

# Comprehensive AsciiDoc Review Report

**Target:** {file_path | directory_path}
**Date:** {ISO timestamp}
**Status:** ✅ PASS | ⚠️ WARNINGS | ❌ FAILURES

## Executive Summary

- Files reviewed: {count}
- Total issues: {count}
- Critical issues: {count}

### Issues by Phase

| Phase | Status | Issues |
|-------|--------|--------|
| Format Validation | {✅/⚠️/❌} | {count} |
| Link Verification | {✅/⚠️/❌} | {count} |
| Content Review | {✅/⚠️/❌} | {count} |

## Phase 1: Format Validation

{Results from validate-format workflow}

## Phase 2: Link Verification

### Broken Links
- {file}:{line} - xref:{target} - {reason}

### False Positives
- {file}:{line} - {link} - Verified manually as valid

### Manual Verification Performed
- {count} links verified with Read tool
- {count} confirmed broken
- {count} false positives

## Phase 3: Content Review

### Promotional Language (ULTRATHINK Analysis)
- Line {N}: "{text}"
  - Issue: {marketing/self-praise/subjective}
  - Reasoning: {ULTRATHINK analysis}
  - Suggestion: "{factual alternative}"

### Missing Sources
- Line {N}: Claim requires citation: "{text}"
  - Type: {performance/compatibility/usage}

### Unverified Claims
- Line {N}: {description}

## Recommendations

### Immediate Actions (Critical)
1. {action required}

### Improvements (Warnings)
1. {suggested improvement}

## Tool Usage Statistics
- validate-format: {time}ms
- verify-links: {time}ms
- review-content: {time}ms
- Total: {time}ms

Workflow: create-from-template

Create new AsciiDoc documents from predefined templates.

What It Creates

• Standard specification documents
• README files
• How-to guides

Parameters

• type (required): standard|readme|guide
• name (required): Document name (used in title and filename)
• path (optional): Output path (default: inferred from type)

Steps

Step 1: Validate Parameters

If type not in [standard, readme, guide]:
  Error: "Invalid type. Use: standard, readme, guide"

If name is empty:
  Error: "Name is required"

Step 2: Determine Output Path

If path not specified:
  standard → standards/{name}.adoc
  readme   → {name}/README.adoc or README.adoc
  guide    → docs/{name}.adoc

Step 3: Load Template

Read template from templates/:

• standard → templates/standard-template.adoc
• readme → templates/readme-template.adoc
• guide → templates/guide-template.adoc

Step 4: Substitute Placeholders

Replace template placeholders:

• {{TITLE}} → Formatted name
• {{PROJECT_NAME}} → Name
• {{GUIDE_TITLE}} → Formatted guide title
• {{DESCRIPTION}} → Empty (user fills in)
• {{SHORT_DESCRIPTION}} → Empty (user fills in)
• {{PURPOSE}} → Empty (user fills in)

Step 5: Write File

Use Write tool to create file at output path.

Step 6: Validate Created File

Execute validate-format workflow on new file.

Step 7: Report Result

Document Created: {output_path}
Type: {type}
Status: ✅ Valid format

Next steps:
1. Edit {output_path} to fill in content
2. Run /doc-doctor target={output_path} to validate

Workflow: sync-with-code

Analyze code changes and update documentation to stay in sync.

What It Does

• Detects code structure changes
• Identifies documentation drift
• Suggests or applies updates

Parameters

• target (required): Documentation file or directory
• code_path (optional): Code directory to analyze (default: src/)

Steps

Step 1: Analyze Code Structure

Use Glob to find code files:
  {code_path}/**/*.java
  {code_path}/**/*.js
  {code_path}/**/*.ts

Extract:
- Public classes/interfaces
- Public methods
- Configuration patterns

Step 2: Analyze Documentation

Read target documentation files
Extract:
- Documented classes/methods
- Code examples
- Configuration references

Step 3: Identify Drift

Compare code vs documentation:

• Missing documentation for new code
• Outdated documentation for changed code
• Documentation for removed code

Step 4: Generate Sync Report

Documentation Sync Analysis
═══════════════════════════════════════

Code analyzed: {file_count} files
Documentation analyzed: {doc_count} files

Drift Detected:
- New code needing docs: {count}
- Outdated documentation: {count}
- Stale documentation: {count}

Details:
{list of specific drift items}

Recommendations:
{specific actions to sync}

Step 5: Apply Updates (if requested)

For each drift item:

• Ask user for confirmation
• Use Edit tool to update documentation
• Re-validate after changes

Workflow: cleanup-stale

Identify and remove stale or duplicate documentation.

What It Does

• Finds duplicate content across files
• Identifies orphaned documentation
• Suggests cleanup actions

Parameters

• target (required): Directory to analyze

Steps

Step 1: Discover Documentation

Use Glob: {target}/**/*.adoc
Exclude: target/, node_modules/

Step 2: Analyze Content

For each file:

• Extract title and sections
• Calculate content hash
• Track cross-references

Step 3: Identify Candidates

Duplicates:

• Files with >80% similar content
• Identical sections across files

Orphaned:

• Files not referenced from anywhere
• Files with broken incoming links

Stale:

• Files with TODO markers older than threshold
• Files not updated in extended period

Step 4: Generate Cleanup Report

Documentation Cleanup Analysis
═══════════════════════════════════════

Files analyzed: {count}

Candidates for Cleanup:
- Potential duplicates: {count}
- Orphaned files: {count}
- Stale content: {count}

Duplicates:
{file1} ↔ {file2}: {similarity}%

Orphaned:
{file}: No incoming references

Stale:
{file}: Contains {N} TODOs

Recommendations:
1. {specific action}

Step 5: Execute Cleanup (with confirmation)

For each approved removal:

1. Update files that reference removed content
2. Remove or consolidate file
3. Re-validate cross-references

Workflow: refresh-metadata

Update metadata, fix cross-references, and refresh table of contents.

What It Does

• Updates document metadata
• Fixes broken cross-references
• Regenerates table of contents

Parameters

• target (required): File or directory

Steps

Step 1: Discover Files

If target is file:
  files = [target]
If target is directory:
  Use Glob: {target}/**/*.adoc

Step 2: Analyze Metadata

For each file:

• Check header attributes (:toc:, :sectnums:, etc.)
• Identify missing or outdated metadata

Step 3: Analyze Cross-References

Execute verify-links workflow
Collect: broken internal references

Step 4: Fix Cross-References

For each broken reference:

1. Search for target content by title/anchor
2. If found at new location: Update reference
3. If not found: Report for manual review

Step 5: Update Metadata

Using Edit tool:

• Ensure standard header attributes present
• Fix attribute formatting

Step 6: Generate Report

Metadata Refresh Complete
═══════════════════════════════════════

Files processed: {count}

Updates Applied:
- Metadata fixed: {count}
- Cross-references fixed: {count}
- Headers updated: {count}

Manual Review Needed:
- {file}: {reason}

Reference Documents

All reference material is in the references/ directory (lookup material - WHAT rules to apply):

Workflow Documents

All workflow procedures are in the workflows/ directory (operational procedures - HOW to execute):

Scripts

Script: pm-documents:ref-documentation → docs.py

Usage Examples:

# Generate statistics
python3 .plan/execute-script.py pm-documents:ref-documentation:docs stats -f json /path/to/docs

# Validate formatting
python3 .plan/execute-script.py pm-documents:ref-documentation:docs validate /path/to/file.adoc

# Format files
python3 .plan/execute-script.py pm-documents:ref-documentation:docs format -t all /path/to/docs

# Verify links
python3 .plan/execute-script.py pm-documents:ref-documentation:docs verify-links --directory /path/to/docs

# Analyze tone
python3 .plan/execute-script.py pm-documents:ref-documentation:docs analyze-tone --file /path/to/file.adoc --output report.json

Usage from Commands

Commands invoke this skill and its workflows:

# In command file
Skill: pm-documents:ref-documentation

# Then specify workflow
Execute workflow: format-document
Parameters:
  target: "standards/"

Quality Verification Checklist

All documentation must pass:

• Professional, neutral tone (no marketing language)
• Proper AsciiDoc formatting
• Complete code examples
• Verified references
• Consistent terminology
• Documents only existing features
• All links valid