Human Documentation Generator

Purpose

This skill transforms detailed AI documentation stored in ai/ folder into human-friendly documentation in docs/ folder. It creates summaries, quick starts, and visual diagrams that enable humans to quickly understand and operate complex systems.

Key principle: ai/ folder remains the source of truth (detailed, comprehensive, for AI context). docs/ folder contains human-optimized extracts (summaries, diagrams, quick references).

When to Use This Skill

Use this skill when:

• User needs human-readable documentation from AI context docs
• AI documentation is too detailed for quick human consumption
• System complexity requires visual diagrams for understanding
• Need quick start guides or executive summaries
• User specifically mentions difficulty following AI documentation
• Creating onboarding materials for new team members
• Extracting crucial information for operational quick reference

Trigger phrases:

• "Create human docs for..."
• "I can't follow the AI documentation"
• "Make this easier to understand"
• "Create a quick start guide"
• "Add diagrams to explain..."
• "Summarize the AI docs"

Core Principles

1. Parallel Structure Maintained

ai/                          docs/
├── architect/               ├── architect/
│   ├── app/                │   ├── app/
│   │   └── 01_DOC.md       │   │   └── 01_DOC_SUMMARY.md
│   └── src/                │   └── src/
│       └── 01_DOC.md       │       └── 01_DOC_QUICKSTART.md
├── backend/                ├── backend/
├── frontend/               ├── frontend/
└── testing/                └── testing/

Key rule: docs/ mirrors ai/ structure but contains human-optimized versions

2. Three Human-Friendly Formats

For each AI doc, create ONE or MORE of:

1. SUMMARY (*_SUMMARY.md)

   • Executive summary (1-2 paragraphs)
   • Key points (bullet list)
   • Quick decision aids
   • 20% of original length

2. QUICKSTART (*_QUICKSTART.md)

   • Step-by-step getting started
   • 5-minute read maximum
   • Code examples
   • Common pitfalls
   • Success criteria

3. DIAGRAMS (*_DIAGRAMS.md)

   • Visual representation with Mermaid.js
   • Architecture diagrams
   • Flow charts
   • Sequence diagrams
   • Entity relationships

3. Mermaid Diagram Guidelines

Always use Mermaid.js for diagrams (renders in GitHub, VS Code, most markdown viewers):

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Diagram types to use:

• graph TD - Top-down flowcharts
• sequenceDiagram - API/interaction flows
• erDiagram - Database schemas
• journey - User journeys
• stateDiagram-v2 - State machines
• gantt - Timelines/roadmaps

See references/mermaid_examples.md for templates

Workflows

Workflow 1: Create Summary from AI Doc

Input: Path to AI documentation file (e.g., ai/architect/app/02_BACKEND_REQUIREMENTS.md)

Process:

1. Read AI documentation thoroughly
2. Identify the 20% most crucial information
3. Create executive summary (2-3 paragraphs)
4. Extract key points (5-10 bullets)
5. Add quick reference table
6. Save to parallel location in docs/ with _SUMMARY.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md

Template: assets/templates/summary_template.md

Workflow 2: Create Quick Start Guide

Input: Path to AI documentation file

Process:

1. Read AI documentation
2. Identify "getting started" path
3. Create step-by-step instructions (numbered)
4. Add code snippets/commands
5. Include success criteria
6. Add "Next steps" section
7. Save to parallel location with _QUICKSTART.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_QUICKSTART.md

Template: assets/templates/quickstart_template.md

Workflow 3: Create Visual Diagrams

Input: Path to AI documentation file OR topic description

Process:

1. Read AI documentation
2. Identify visualizable concepts:
   • System architecture
   • Data flow
   • User journeys
   • Database schemas
   • Decision trees
3. Create Mermaid diagrams (2-5 diagrams)
4. Add explanatory text for each diagram
5. Save to parallel location with _DIAGRAMS.md suffix

Output: docs/architect/app/02_BACKEND_REQUIREMENTS_DIAGRAMS.md

Template: assets/templates/diagrams_template.md

Workflow 4: Batch Process Entire Folder

Input: Path to AI documentation folder (e.g., ai/architect/app/)

Process:

1. List all markdown files in folder
2. For each file, determine best format(s):
   • Architecture docs → SUMMARY + DIAGRAMS
   • Implementation guides → QUICKSTART
   • Specifications → SUMMARY + DIAGRAMS
3. Create human docs in parallel structure
4. Generate index README for docs/ folder
5. Report completion summary

Output: Complete docs/ folder structure

Workflow 5: Update Existing Human Docs

Input: Path to updated AI documentation

Process:

1. Check if human doc already exists in docs/
2. If exists, compare modification dates
3. If AI doc is newer, regenerate human doc
4. Preserve any manual additions (check for "Manual:" markers)
5. Save updated human doc

Output: Updated human documentation

Document Format Standards

SUMMARY Format

# [Original Title] - Summary

**Source:** Link to AI doc
**Last Updated:** Date
**Read Time:** X minutes

## Executive Summary

[2-3 paragraphs capturing essence]

## Key Points

- Point 1
- Point 2
- Point 3

## Quick Reference

| Aspect | Detail |
|--------|--------|
| Key 1  | Value  |

## When to Read Full Doc

- Scenario 1
- Scenario 2

[Link to full documentation]

QUICKSTART Format

# [Topic] Quick Start

**Time to complete:** X minutes
**Prerequisites:** List

## Step 1: [Action]

[Instructions + code/commands]

## Step 2: [Action]

[Instructions + code/commands]

## Success Criteria

✅ Checklist item
✅ Checklist item

## Next Steps

- Link to detailed docs
- Related quick starts

## Troubleshooting

**Issue:** Description
**Fix:** Solution

DIAGRAMS Format

# [Topic] Visual Guide

**Source:** Link to AI doc

## Overview Diagram

```mermaid
[diagram code]

Explanation: What this diagram shows

[Specific Aspect] Diagram

[diagram code]

Explanation: What this diagram shows

Legend

• Symbol → Meaning

Integration with Other Skills

Use with architect skill:

• Architect creates detailed specs in ai/architect/
• Human-docs creates summaries in docs/architect/

Use with business skill:

• Business creates use cases in ai/business/
• Human-docs creates executive summaries

Use with executive skill:

• Executive defines strategy
• Human-docs creates visual roadmaps

Use with cleanup skill:

• Cleanup organizes ai/ folder
• Human-docs regenerates docs/ structure

Quality Standards

Every human doc must have: ✅ Clarity - Understandable without reading AI doc ✅ Conciseness - 20% or less of original length (summaries) ✅ Actionable - Clear next steps ✅ Visual - At least 1 diagram for complex topics ✅ Navigable - Links to source and related docs ✅ Dated - Last updated timestamp

Minimum quality threshold: 8/10

File Naming Conventions

AI doc:     ai/folder/FILE.md
Summary:    docs/folder/FILE_SUMMARY.md
Quickstart: docs/folder/FILE_QUICKSTART.md
Diagrams:   docs/folder/FILE_DIAGRAMS.md

Never:

• Create files in ai/ (only read from there)
• Replace AI documentation
• Duplicate information across formats

Maintenance

When AI docs are updated:

1. Check docs/ for corresponding human docs
2. Regenerate if AI doc is newer
3. Update "Last Updated" timestamp
4. Keep change history minimal (humans don't need full changelog)

Index README regeneration:

• Create docs/README.md with navigation to all human docs
• Group by folder structure
• Add "Quick Links" section

Common Use Cases

Use Case 1: New Team Member Onboarding

Scenario: New developer needs to understand GabeDA architecture

Action:

1. Generate SUMMARY for all ai/architect/app/ docs
2. Generate DIAGRAMS for key architecture concepts
3. Create docs/ONBOARDING.md with curated path
4. Include quick starts for common tasks

Use Case 2: Executive Review

Scenario: Executive needs high-level understanding

Action:

1. Generate executive SUMMARY from technical specs
2. Create visual DIAGRAMS of system architecture
3. 1-page maximum with Mermaid diagrams
4. No technical jargon

Use Case 3: Quick Reference for Developers

Scenario: Developer forgets API endpoint structure

Action:

1. Create QUICKSTART from API documentation
2. Include code examples
3. Add common patterns
4. Link to full spec

Examples

Example 1: Architecture Summary

Input: ai/architect/app/02_BACKEND_REQUIREMENTS.md (14,000 words) Output: docs/architect/app/02_BACKEND_REQUIREMENTS_SUMMARY.md (2,000 words)

Example 2: Quick Start

Input: ai/architect/app/05_CSV_UPLOAD_SPECIFICATION.md Output: docs/architect/app/05_CSV_UPLOAD_QUICKSTART.md

• 5 steps to implement CSV upload
• Code snippets
• 10-minute read

Example 3: Visual Guide

Input: ai/architect/app/07_WORKFLOWS_AND_DATA_FLOW.md Output: docs/architect/app/07_WORKFLOWS_DIAGRAMS.md

• Already has diagrams, extract and simplify
• Add annotations
• Create simplified version

Version History

v1.0.0 (2025-11-01)

• Initial skill creation
• Support for SUMMARY, QUICKSTART, DIAGRAMS formats
• Mermaid diagram integration
• Parallel folder structure

---

Last Updated: 2025-11-01 Skill Type: Documentation transformation and visualization