Human Docs Generator Skill Skill

Human Docs Generator Skill

Role

Automatically generates and maintains role-specific documentation for humans when significant changes occur in the system.

Purpose

Transform complex AI state and technical implementations into simple, role-specific guides that humans can actually understand and use.

Trigger Conditions

Automatic Triggers

✅ Epic completed
🔧 Public API modified
🎯 New user feature deployed
💥 Breaking change introduced
🐛 Critical bug fixed
📊 5+ related tasks completed

Manual Trigger

{
  "event": "generate.human.docs",
  "scope": "all|specific-role",
  "reason": "manual request"
}

Document Structure

Files Maintained

ai-state/human-docs/
├── INDEX.md                 # Role directory & quick nav
├── frontend-developer.md    # React, components, routes
├── backend-developer.md     # APIs, models, database
├── architect.md            # System design, patterns
├── devops.md              # Deploy, monitor, debug
├── tester.md              # Test suites, coverage
├── product-manager.md     # Features, metrics, roadmap
└── end-user-guide.md      # Screenshots, how-to-use

Generation Process

1. Gather Context

sources:
  - ai-state/active/     # Current implementations
  - ai-state/knowledge/  # Patterns and decisions
  - operations.log       # Recent changes
  - test-results/        # What's working

2. Extract Role-Relevant Info

Frontend Developer Needs

Component locations & hierarchy
State management patterns
Reusable components list
Recent UI changes

Backend Developer Needs

API endpoint documentation
Database schema changes
Authentication flow
Service dependencies

End User Needs

Screenshots with annotations
Step-by-step guides
Feature locations
Common workflows

3. Transform to Human Format

Rules for Human Docs

Max 1000 words per document
Diagrams over text (Mermaid.js)
Examples over explanations
Current state only (no history)
Quickstart focused

4. Generate Diagrams

Component Tree (Frontend)

graph TD
    App --> Header
    App --> Routes
    Routes --> Login
    Routes --> Dashboard
    Dashboard --> Charts
    Dashboard --> Tables

API Flow (Backend)

sequenceDiagram
    User->>Frontend: Click Login
    Frontend->>API: POST /auth/login
    API->>Database: Validate credentials
    Database->>API: User data
    API->>Frontend: JWT token
    Frontend->>User: Dashboard

User Flow (End User)

graph LR
    Start[Open App] --> Login[Enter Email/Pass]
    Login --> Dash[View Dashboard]
    Dash --> Upload[Upload Data]
    Upload --> Process[Wait for Processing]
    Process --> View[View Results]
    View --> Export[Download Report]

Document Templates

Frontend Developer Template

# Frontend Developer Guide

## Quick Start
[3-step setup process]

## Component Map
[Mermaid diagram of components]

## To Add a New Page
1. Create component in `/src/pages/`
2. Add route in `/src/routes.tsx`
3. Update navigation in `/src/components/Nav.tsx`

## Available Components
- `<Button>` - Primary actions
- `<Card>` - Content containers
- `<Table>` - Data display
[List reusable components]

## State Management
[Current state shape diagram]

## Recent Changes
- ✅ Added password reset
- ✅ Updated dashboard layout

End User Template

# How to Use [App Name]

## Getting Started
[Screenshot of login page with arrows]

## Main Features

### Upload Data
1. Click "Upload" button (top-right)
2. Select your CSV file
3. Click "Process"
[Screenshot with numbered steps]

### View Reports
[Screenshot of reports page]
- Yellow box = Warnings
- Green box = Success
- Red box = Errors

## Common Tasks
**Q: How do I reset my password?**
A: Click "Forgot Password" on login page

**Q: Where are my old reports?**
A: Click "History" in sidebar

Quality Checks

Before Publishing

[ ] Under 1000 words?
[ ] Has diagrams/screenshots?
[ ] Includes quickstart?
[ ] Examples provided?
[ ] No technical jargon?
[ ] Tested instructions work?

Integration

Input Events

{
  "event": "epic.completed",
  "epic_id": "epic-oauth",
  "tasks_completed": ["task-001", "task-002"],
  "changes": ["Added Google login"]
}

Output Events

{
  "event": "human.docs.updated",
  "files": [
    "frontend-developer.md",
    "end-user-guide.md"
  ],
  "sections_changed": [
    "authentication",
    "login-methods"
  ]
}

Anti-Patterns to Avoid

❌ Writing changelogs (just current state) ❌ Technical deep-dives (keep it simple) ❌ Walls of text (use bullets/diagrams) ❌ Assuming knowledge (explain everything) ❌ Version history (one living document)

Success Metrics

Reading time < 5 minutes
Diagram-to-text ratio > 40%
Quickstart success rate > 90%
Human confusion tickets < 5%
Doc update frequency = feature frequency

Agent Skills: Human Docs Generator Skill

Install this agent skill to your local

Skill Files