Documentation Generator

Restructure and organize project documentation for clarity and accessibility.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

0. Create Feature Branch

Before making any changes:

Check the current branch - if already on a feature branch for this task, skip
Check the repo for branch naming conventions (e.g., feat/, feature/, etc.)
Create and switch to a new branch following the repo's convention, or fallback to: feat/docs-generator

1. Analyze Project

Read the codebase to identify:

Project type: Library, API, web app, CLI, microservices
Architecture: Monorepo, multi-package, single module
User personas: End users, developers, operators
Existing docs: Scan for README files, docs/ folder, inline comments, docstrings
Gaps: List what documentation exists vs. what is missing

2. Restructure Documentation

Root README.md - Streamline as entry point:

Project overview and purpose
Quickstart (install + first use)
Modules/components summary with links
License and contacts

Component READMEs - Add per module/package/service:

Purpose and responsibilities
Setup instructions
Testing commands

Centralize in docs/ - Organize by category (select applicable):

docs/
├── architecture.md      # System design, diagrams
├── api-reference.md     # Endpoints, authentication
├── database.md          # Schema, migrations
├── deployment.md        # Production setup
├── development.md       # Local setup, contribution
├── troubleshooting.md   # Common issues
└── user-guide.md        # End-user documentation

3. Create Diagrams

Use Mermaid for all visual documentation:

Architecture diagrams
Data flow diagrams
Database schemas

4. Review and Validate

Verify all internal links resolve correctly
Check that code examples in docs are syntactically valid
Confirm no orphaned docs (files not linked from anywhere)
Present a summary of changes to the user before committing

Error Handling

No existing documentation found

Solution: Generate documentation from scratch based on code analysis. Start with README.md and add docs/ files based on project complexity.

Conflicting or outdated docs

Solution: Flag conflicts to the user. Prefer code-derived information over stale docs. Mark outdated sections for user review.

Guidelines

Keep docs concise and scannable
Adapt structure to project type (not all categories apply)
Maintain cross-references between related docs
Remove redundant or outdated content
Preserve any existing docs that are still accurate

docs-generator