octocode-documentation-writer_skill

Overview

This skill orchestrates a production-ready, 6-phase pipeline that analyzes a TypeScript codebase and generates conflict-free, evidence-backed documentation files. It uses coordinated AI subagents (discovery, research, orchestrator, writers, QA) to discover architecture, generate engineering questions, do code forensics, assign exclusive file ownership, write docs, and validate quality. The goal is comprehensive developer and API documentation that maps directly to repository files.

How this skill works

The pipeline runs these phases: parallel discovery to produce analysis.json, question synthesis, parallel research to answer questions with code evidence, orchestration to assign file ownership, parallel writers to produce documentation/*.md, and a QA validator that verifies outputs and emits qa-results.json and QA-SUMMARY.md. Pre-flight checks and workspace initialization guard against incorrect paths, build directories, tiny repos, and oversized codebases. Parallel agent execution is enforced by spawning all parallel tasks in a single message to preserve concurrency and avoid file conflicts.

When to use it

• You need to generate or update comprehensive docs for a codebase (APIs, onboarding, developer guides).
• You want evidence-backed documentation tied to specific files and implementations.
• You need conflict-free, parallel documentation generation across many files.
• You want a reproducible pipeline that outputs analysis.json, research.json, work-assignments.json, and documentation/*.md.
• You need QA-validated docs with LSP-powered verification.

Best practices

• Run pre-flight checks and confirm repository path, directory status, and size before starting.
• Ensure repository root (not a build directory) and exclude node_modules/dist/build from the path.
• Allow the pipeline to resume when a valid state.json exists to avoid wasted work.
• Batch and split questions before spawning researcher agents so each researcher has an exclusive scope.
• Always spawn all parallel agents for a phase in a single message to maintain concurrency and avoid sequential slowdowns.

Example use cases

• Create developer onboarding docs and architecture overview for a TypeScript service before handing project to new hires.
• Generate API reference and implementation links for public or private repos to accelerate code review and audits.
• Document a large repository incrementally by resuming from state.json after addressing pre-flight warnings.
• Produce file-level docs for a microservice repo by assigning exclusive writers per file to avoid merge conflicts.
• Validate and publish documentation with a QA summary that surfaces missing evidence or inaccurate claims.