documentation

Documentation Skill

Ensures all documentation follows project standards and prevents redundant files.

Purpose

This skill provides tools and workflows for efficient documentation management:

• Section-level interaction scripts (search, get, update without reading full files)
• Document templates for consistent structure
• Workflows for common documentation tasks
• Rules and standards to prevent redundancy

When to Use This Skill

Use this skill when:

• Creating new documentation for features, screens, or architecture
• Updating existing documentation after code changes
• Finding and consolidating duplicate documentation
• Splitting large documentation files (>500 lines)
• Searching for specific information in docs
• Checking documentation quality and compliance

Core Principles

1. DRY (Don't Repeat Yourself)

• Check for existing documentation before creating new files
• Update existing docs instead of creating duplicates
• Consolidate related information into single files

2. Screen-Based Organization

docs/
├── README.md              # Master index (DO NOT MODIFY)
├── guides/                # User and developer guides
├── architecture/          # Architecture docs
└── screens/               # Screen-specific docs
    └── {screen-name}/
        ├── README.md      # Overview (required)
        ├── features.md    # Features (optional)
        ├── technical.md   # Technical (required)
        └── flows.md       # Flows (optional)

3. Size Limits

• Maximum 500 lines per file
• Split files approaching limit (>450 lines)
• Keep documents focused and scannable

How to Use This Skill

Step 1: Check for Existing Documentation

Use scripts for efficient search (80-98% context reduction):

# Search without reading full files
./scripts/doc-search.sh "topic-keyword"

# Get file metadata (0 lines read)
./scripts/doc-metadata.sh docs/path/to/file.md

# List sections to navigate (structure only)
./scripts/doc-list-sections.sh docs/file.md

Complete script documentation: See scripts/README.md

Step 2: Determine Action

If similar documentation exists:

• Load workflow: references/workflows/update-existing.md
• Use doc-get-section.sh to read only relevant section
• Update section with doc-update-section.sh

If creating new documentation:

• Load workflow: references/workflows/create-screen.md
• Load template: assets/templates/screen-readme.md or assets/templates/screen-technical.md
• Follow template structure

If file is too large (>450 lines):

• Load workflow: references/workflows/split-large-file.md

If duplicates found:

• Load workflow: references/workflows/consolidate-duplicates.md

Step 3: Validate Against Rules

Load reference file: references/rules.md

Check:

• ✅ No duplicate content exists
• ✅ File under 500 lines
• ✅ Code references include file:line format
• ✅ All code blocks have language specified
• ✅ Examples are tested and working

Complete rules: See references/rules.md

Bundled Resources

Scripts (scripts/)

Efficient section-level interaction tools:

• doc-search.sh - Search content without reading full files
• doc-list-sections.sh - List all headings with line numbers
• doc-get-section.sh - Extract specific section only (90% context reduction)
• doc-update-section.sh - Update section without reading full file
• doc-delete-section.sh - Remove section
• doc-insert-after.sh - Insert content after section
• doc-metadata.sh - Get file statistics (100% context reduction)
• doc-find-duplicates.sh - Find redundant content

Benefits: 80-98% reduction in context usage vs reading entire files

Complete documentation: scripts/README.md

References (references/)

Load as needed for detailed information:

• rules.md - Complete documentation rules and anti-patterns
• structure.md - Directory organization details and navigation
• examples.md - Real examples from this project (good vs bad patterns)
• workflows/ - Step-by-step workflows for common tasks:
  • create-screen.md - Creating new screen documentation
  • update-existing.md - Updating existing documentation
  • consolidate-duplicates.md - Consolidating duplicate docs
  • split-large-file.md - Splitting files >500 lines
  • add-examples.md - Adding examples to docs
  • review-quarterly.md - Quarterly documentation review

Assets (assets/)

Templates used in documentation output:

• templates/ - Document templates:
  • screen-readme.md - For docs/screens/{name}/README.md
  • screen-technical.md - For docs/screens/{name}/technical.md
  • screen-features.md - For docs/screens/{name}/features.md
  • screen-flows.md - For docs/screens/{name}/flows.md
  • architecture.md - For docs/architecture/*.md
  • guide.md - For docs/guides/*.md

Progressive Disclosure

This skill uses filesystem-based progressive disclosure:

Level 1: Metadata (always in context)

• Skill name and description (~100 words)

Level 2: SKILL.md (when skill triggers)

• Core instructions and workflow guidance (~2k words)

Level 3: Bundled resources (loaded as needed)

• Scripts: Execute without reading into context
• References: Load specific file when detailed info needed
• Assets: Copy template into output

Example: Creating screen docs

• Before: Read all 3,620 lines
• After: SKILL.md (300 lines) + workflow (150 lines) + template (200 lines) = 650 lines (82% reduction)

Typical Workflows

Creating New Screen Documentation

1. Check: ./scripts/doc-search.sh "ScreenName"
2. If not exists: Load references/workflows/create-screen.md
3. Follow workflow:
   • Create directory: docs/screens/{screen-name}
   • Use template: assets/templates/screen-readme.md
   • Use template: assets/templates/screen-technical.md
   • Validate against: references/rules.md

Updating Existing Documentation

1. Get metadata: ./scripts/doc-metadata.sh docs/file.md
2. List sections: ./scripts/doc-list-sections.sh docs/file.md
3. Get section: ./scripts/doc-get-section.sh docs/file.md "Section"
4. Update section: ./scripts/doc-update-section.sh docs/file.md "Section" new-content.md

Finding and Removing Duplicates

1. Find duplicates: ./scripts/doc-find-duplicates.sh docs/
2. Load workflow: references/workflows/consolidate-duplicates.md
3. Follow consolidation steps
4. Delete redundant files

Questions to Ask User

Before creating documentation:

• "Found similar docs at {path}. Update existing instead of creating new?"
• "Is this feature complete and ready to document?"
• "Should this go in screens/{screen}/, guides/, or architecture/?"
• "File is 450+ lines. Should split into multiple files?"

Success Criteria

Good documentation is:

• ✅ Easy to find (follows structure in references/structure.md)
• ✅ Easy to read (under 500 lines)
• ✅ No duplicates (DRY principle)
• ✅ Up to date (matches current code)
• ✅ Actionable (includes tested examples)
• ✅ Traceable (code references with file:line format)