Doc Generation

Store this path in a variable for use throughout:

SKILL_SCRIPTS="/absolute/path/to/.claude/skills/doc-generation/scripts"

Pre-flight Checks

Before starting, verify these in order:

1. Python 3.11+

python3 --version

If not available, stop and tell the user.

2. Parser Dependencies

python3 "$SKILL_SCRIPTS/analyze_repo.py" --check-deps /path/to/repo

When a repo path is provided, this scans the repo for file extensions, determines which languages are present, and only checks whether those parsers are installed. It exits 0 if all needed parsers are available, exits 1 if any are missing.

Without a repo path, it checks all parsers globally (useful for a one-time environment setup).

If needed parsers are missing, the command prints install instructions. Python analysis uses stdlib ast and never requires tree-sitter.

3. Git Repository

The target repo must be a git repository. If git rev-parse HEAD fails in the repo directory, stop and tell the user: "This directory is not a git repository. Documentation versioning requires git."

4. Fresh vs Update

Check if docs/wiki/.doc-meta.json exists in the target repo:

• Does NOT exist → follow Fresh Generation below
• Exists → follow Update Existing Documentation below

Fresh Generation

Phase 1 — Structural Analysis

Run the analysis script. Determine the absolute path to the scripts directory first.

python3 "$SKILL_SCRIPTS/analyze_repo.py" /path/to/repo --output /path/to/repo/.doc-analysis.json

Scoping options (pass as needed):

• --include "*.py,*.ts" — Only analyze files matching these patterns
• --exclude "*test*,*spec*,*mock*" — Skip files matching these patterns
• --focus "src/core,src/api" — Tag directories for deeper documentation (see Phase 3)
• --max-files 300 — Limit total files analyzed
• --verbose — Show detailed logging

Read the output JSON with the Read tool. Report to the user:

• Number of files analyzed
• Number of components found
• Number of relationships discovered
• Languages detected and parsed
• Languages skipped (if any — this means parsers were missing)

Critical check: If languages_skipped is non-empty, stop and warn the user. Offer two options:

1. Install the missing parsers and re-run
2. Proceed with partial analysis (documentation will only cover parsed languages)

If >200 components, warn: "This repo has {N} components. Documentation generation will be token-intensive. Proceed?"

If >500 components, suggest phased approach: "Consider documenting core modules first using --include to scope to specific directories. Which areas are most important?"

Phase 2 — Module Clustering

Using the analysis JSON, group components into logical modules. This is your reasoning — no external tool needed.

Clustering heuristics (apply in order):

1. File path proximity: Components in the same directory or subdirectory belong together. Group by the first 2-3 path segments (e.g., src/auth/* → "authentication" module).

2. Dependency relationships: Components that call each other frequently belong together. Use the relationships array from the analysis.

3. Naming conventions: Components with common prefixes or domain terms (auth, db, api, payment, user) form natural modules.

4. For small repos (<30 components): Skip clustering. Document everything in a single comprehensive overview.

5. For large repos (>100 components): Create hierarchical sub-modules. A top-level module like "api-layer" might have sub-modules for routes, middleware, and validators.

Module naming: Use lowercase-with-hyphens for all module names. These become filenames: authentication.md, database-layer.md, api-routes.md.

Persist the module tree: Write docs/wiki/module-tree.json with the clustering result:

{
  "authentication": {
    "components": ["src.auth.service.AuthService", "src.auth.models.User"],
    "description": "User authentication and session management",
    "doc_file": "authentication.md"
  },
  "database-layer": {
    "components": ["src.db.pool.ConnectionPool", "src.db.models.BaseModel"],
    "description": "Database connection and ORM layer",
    "doc_file": "database-layer.md"
  }
}

Phase 3 — Module Documentation

Process modules leaf-first (modules with no sub-modules first, then parent modules).

Focus areas: If --focus was used, each component in the analysis JSON has an is_focus field (true/false). Modules containing focus components get deeper documentation: more detailed component descriptions, more code snippets, additional Mermaid diagrams for internal flows. Non-focus modules get standard documentation.

For each module, use the Read tool to read the actual source files of its components, then write a markdown documentation file.

Each module doc ({module-name}.md) should include:

1. Module Overview — 2-3 sentences describing purpose and responsibility
2. Architecture Diagram — Mermaid diagram showing components and their relationships within the module:

   graph TD
     A[ComponentA] --> B[ComponentB]
     B --> C[ComponentC]
   

3. Component Descriptions — For each key component:
   • What it does
   • Key methods/functions and their purpose
   • Important parameters and return types
4. Dependencies — Mermaid diagram showing what other modules this module depends on:

   graph LR
     ThisModule --> DatabaseModule
     ThisModule --> ConfigModule
   

5. Key APIs — The most important public interfaces with brief usage notes
6. Cross-references — Links to related module docs using the exact filename: [Database Layer](database-layer.md)

Important rules:

• All .md files go in the same flat directory (docs/wiki/)
• Cross-reference format: [Display Name](filename.md) — all files are siblings, filenames use lowercase-with-hyphens
• Include source code snippets for key interfaces — short, focused excerpts
• Mermaid diagrams should be clear and not overly complex — 5-15 nodes max per diagram

Phase 4 — Repository Overview

After all module docs are written, generate overview.md:

1. Repository Purpose — What this codebase does, in 2-3 sentences
2. Architecture Overview — Top-level Mermaid diagram showing all modules and their relationships:

   graph TD
     API[API Layer] --> Auth[Authentication]
     API --> DB[Database]
     Auth --> DB
     API --> Cache[Cache Layer]
   

3. Module Index — Table linking to all module documentation files with one-line descriptions
4. Technology Stack — Languages, key frameworks, and tools detected
5. Getting Started — Brief orientation for a developer new to the codebase

Phase 5 — Validation

Before declaring success, verify:

1. Cross-reference links: Scan each generated .md file for markdown links of the form [...](*.md). Verify every linked filename exists in docs/wiki/. Report any broken links.

2. Mermaid diagrams: Scan each file for mermaid code blocks. Read each one and verify:

   • It starts with a valid diagram type (graph, flowchart, sequenceDiagram, classDiagram, stateDiagram, erDiagram)
   • Node and edge syntax is well-formed
   • No obvious syntax errors (unclosed brackets, invalid arrows) If any diagram looks invalid, fix it before proceeding.

3. Completeness: Every module in module-tree.json has a corresponding .md file. The overview.md exists and links to all modules.

4. No empty sections: Scan for markdown headings followed immediately by another heading or end-of-file with no content between them. Fill or remove empty sections.

Phase 6 — Metadata

Write .doc-meta.json to the output directory:

{
  "generated_at": "2026-03-14T10:30:00Z",
  "commit_hash": "abc123def456",
  "module_tree": {
    "authentication": {
      "components": ["src.auth.service.AuthService"],
      "doc_file": "authentication.md"
    }
  },
  "files_generated": ["overview.md", "authentication.md", "database-layer.md"],
  "component_count": 142,
  "repo_name": "my-service",
  "output_path": "docs/wiki",
  "scoping": {
    "include_patterns": null,
    "exclude_patterns": null
  }
}

Report completion: "Documentation generated: {N} module docs + overview. Output: docs/wiki/"

Update Existing Documentation

Use this flow when .doc-meta.json already exists.

Step 1 — Detect Staleness

Read docs/wiki/.doc-meta.json using the Read tool. Extract the commit_hash field.

Run git rev-parse HEAD in the repo directory to get the current commit.

If they match, docs are current. Tell the user: "Documentation is up to date (generated at commit {hash})."

If they differ, proceed.

Step 2 — Compute Changes

git diff --name-only {stored_hash} HEAD

This gives you the list of files that changed since docs were last generated.

Step 3 — Re-run Analysis

Run the analysis script again, using the same scoping options from .doc-meta.json if they were set:

python3 "$SKILL_SCRIPTS/analyze_repo.py" /path/to/repo --output /path/to/repo/.doc-analysis.json

Step 4 — Identify Affected Modules

Read the new analysis JSON and the stored .doc-meta.json module tree. Compare:

1. Changed components: Any component whose relative_path appears in the git diff file list
2. New components: Components in the new analysis that don't exist in the stored module tree
3. Removed components: Components in the stored module tree that don't appear in the new analysis
4. Changed relationships: New or removed dependency edges

A module is affected if any of its components were changed, added, or removed.

Step 5 — Re-cluster if Needed

• If only content changed within existing files (no new files, no deleted files): keep existing module tree
• If new files were added or files were deleted: re-evaluate clustering for affected areas. New components may belong to existing modules or may warrant a new module.

Step 6 — Regenerate Affected Docs

For each affected module:

1. Re-read the current source code of its components
2. Rewrite that module's markdown file with updated content
3. Update Mermaid diagrams to reflect any structural changes

For unaffected modules: leave their docs untouched.

Step 7 — Validate and Update Metadata

Run the same validation checks from Phase 5 of Fresh Generation (cross-references, Mermaid, completeness, empty sections).

If any module was affected:

1. Regenerate overview.md to ensure it reflects current state
2. Update .doc-meta.json with new commit hash, timestamp, and module tree

Report: "Updated documentation for {N} modules. {M} modules unchanged."

Output Directory Structure

docs/wiki/
├── .doc-meta.json          # Generation metadata (commit hash, module tree, scoping)
├── module-tree.json        # Module clustering structure
├── overview.md             # Repository overview with architecture diagram
├── authentication.md       # Module documentation
├── database-layer.md       # Module documentation
├── api-routes.md           # Module documentation
└── ...                     # Additional module docs

When to Stop and Ask

Do not proceed silently in these situations:

• Repo has no supported languages: Stop. Tell the user which languages were detected and that none have parsers.
• More than 20% of files failed analysis: The output is unreliable. Stop and recommend installing missing parsers.
• No git history: The commit hash is "unknown." Warn the user that update/staleness tracking won't work.
• Large repo with no scoping: If >500 components, recommend using --include or --exclude to focus on core areas first.
• Existing docs in a different format: If docs/wiki/ exists but has no .doc-meta.json, it wasn't generated by this skill. Ask whether to overwrite or use a different output path.

Documentation Quality Guidelines

Good documentation answers: What does this do? Why does it exist? How does it connect to the rest of the system? How would I use or modify it?

Mermaid diagram types to use:

• graph TD or graph LR — Architecture and dependency diagrams
• sequenceDiagram — For request/response flows or multi-step processes
• classDiagram — For class hierarchies (use sparingly)
• flowchart — For decision trees or process flows

What to include:

• Purpose and responsibility of each module
• How modules connect to each other
• Key interfaces and their contracts
• Source code snippets for important APIs (brief, focused)
• Mermaid diagrams for visual understanding

What NOT to include:

• Line-by-line code commentary
• Implementation details obvious from reading the code
• Test file documentation
• Configuration file documentation (unless critical to understanding architecture)
• Speculative or aspirational content — document what IS, not what could be