Ops Docs

Operational Documentation Generator

You are generating operational documentation for a mission-critical TypeScript project. This skill consolidates multiple documentation types into a single workflow. Unlike /project-docs (which handles standard project files like README, LICENSE, CONTRIBUTING), this skill focuses on operational and technical documentation.

Available Document Types

Instructions

1. Determine document types

If $ARGUMENTS is provided, parse it as a comma-separated list of keys. Otherwise, ask the user which documents to generate using a multi-select question.

2. Load context

• Read package.json for project name, dependencies, scripts
• Read CLAUDE.md and README.md for project description
• Scan src/ directory structure to understand module layout
• Read .claude/docs/TypeScript Coding Standard for Mission-Critical Systems.md if present

Type: runbooks — Operational Runbooks

1. Ask the user for:

   • Service name
   • Known dependencies (databases, caches, external APIs, message queues)
   • Common operational scenarios they want documented (or use defaults)

2. Create docs/runbooks/ directory with:

   docs/runbooks/TEMPLATE.md: Blank runbook template

   # RB-NNN: <Title>
   
   **Severity**: SEV1 | SEV2 | SEV3 | SEV4
   **Last reviewed**: YYYY-MM-DD
   **Owner**: <team/person>
   
   ## Trigger Conditions
   
   <What alert or symptom initiates this runbook>
   
   ## Prerequisites
   
   - Required access: ...
   - Required tools: ...
   - Relevant dashboards: ...
   
   ## Diagnostic Steps
   
   1. ...
   2. ...
   
   ## Remediation Steps
   
   1. ...
   2. ...
   
   ## Rollback / Undo
   
   1. ...
   
   ## Escalation
   
   - When to escalate: ...
   - Contact: ...
   
   ## Post-Incident Verification
   
   1. Confirm the issue is resolved: ...
   2. Monitor for recurrence: ...
   
   ## Related Runbooks
   
   - [RB-NNN: Related Title](./related.md)
   

   Default runbooks (generate these unless the user specifies otherwise):

   • high-latency.md — Diagnosing and resolving slow response times
   • database-connection-failure.md — Handling database connectivity issues
   • out-of-memory.md — Diagnosing memory leaks and OOM kills
   • deployment-rollback.md — Rolling back a bad deployment
   • dependency-outage.md — Handling upstream service outages
   • certificate-expiry.md — Rotating expired TLS certificates

   docs/runbooks/README.md: Index table of all runbooks with ID, title, severity, and trigger.

Type: incident-playbook — Incident Response Playbook

1. Ask the user for:

   • Team/organization name
   • On-call rotation tool (PagerDuty, OpsGenie, or none)
   • Communication channels (Slack workspace, status page URL)
   • Escalation contacts (or use placeholders)

2. Create docs/incidents/ directory with:

   docs/incidents/playbook.md:

   • Severity definitions (SEV1-SEV4) with impact criteria, response time targets, and communication cadence
   • Roles: Incident Commander, Communications Lead, Subject Matter Expert, Scribe — each with responsibilities
   • Incident lifecycle: Detection → Triage → Mitigation → Resolution → Post-mortem
   • Communication templates: Slack incident channel message, status page update, stakeholder email (one per severity level)
   • Escalation matrix with contact placeholders

   docs/incidents/post-mortem-template.md (blameless, modeled on Google SRE):

   • Incident summary (what happened, duration, impact)
   • Timeline (with timestamps)
   • Root cause analysis (5 Whys method)
   • Impact assessment (users affected, data loss, revenue impact)
   • What went well / What went poorly / Where we got lucky
   • Action items (owner, priority, due date)
   • Lessons learned

   docs/incidents/severity-matrix.md: Detailed severity classification with examples.

   .github/ISSUE_TEMPLATE/incident.yml: GitHub Issue template for tracking incidents with structured fields.

Type: architecture — Architecture Diagrams (C4 Model)

1. Analyze the project:

   • Scan src/ directory structure — each subdirectory is a module
   • Parse import statements across all .ts files to build a dependency graph
   • Identify external dependencies from package.json (databases, HTTP clients, message queues)
   • Read package.json description and README.md for system context

2. Generate C4 diagrams in Mermaid syntax (renders natively in GitHub):

   docs/architecture/context.md — System Context diagram:

   • The system as a box in the center
   • External actors (users, external APIs, databases) around it
   • Arrows showing interactions

   docs/architecture/components.md — Component diagram:

   • Each src/ subdirectory as a component box
   • Import relationships as arrows (with direction)
   • External dependencies grouped separately
   • Flag circular dependencies with a warning

   docs/architecture/dependencies.md — Module dependency graph:

   • Text-based tree showing which modules import which
   • Import counts per module
   • Circular dependency detection

   docs/architecture/README.md: Index with descriptions and links.

3. All diagrams use Mermaid code blocks:

   ```mermaid
   graph TD
     A[Module A] --> B[Module B]
     B --> C[Module C]
   ```
   

Type: api-docs — API Documentation Setup

1. Generate TypeDoc configuration (typedoc.json):

   {
     "entryPoints": ["src/index.ts"],
     "out": "docs/api",
     "plugin": ["typedoc-plugin-markdown"],
     "exclude": ["**/*.test.ts", "**/*.spec.ts"],
     "readme": "none"
   }
   

2. Add npm script: "docs:api": "typedoc" to package.json

3. TSDoc completeness scan: Analyze all exported functions and types. For each public API, check for:

   • Missing @param annotations
   • Missing @returns annotation
   • Missing @throws annotation (Rule 10.1)
   • Missing usage examples for complex functions Report a TSDoc coverage percentage.

4. If HTTP framework detected (Express, Fastify, Hono imports in deps):

   • Ask if the user wants OpenAPI documentation
   • If yes, generate an openapi.yaml skeleton with paths inferred from route definitions
   • Suggest zod-to-openapi for automatic schema generation from existing Zod schemas
   • List install commands: npm install --save-exact -D typedoc typedoc-plugin-markdown

5. Optionally generate a CI job for auto-publishing docs to GitHub Pages on push to main.

Type: license-report — Third-Party License Attribution

1. Scan dependencies: For each production dependency in package.json, determine its license by:

   • Reading node_modules/<pkg>/package.json license field (if node_modules exists)
   • Or running npm view <pkg> license

2. Generate THIRD_PARTY_LICENSES.md:

   # Third-Party Licenses
   
   This project uses the following third-party packages:
   
   | Package | Version | License | Repository                        |
   | ------- | ------- | ------- | --------------------------------- |
   | zod     | 3.22.4  | MIT     | https://github.com/colinhacks/zod |
   | ...     | ...     | ...     | ...                               |
   

3. Generate or update license-policy.json:

   {
     "allowed": ["MIT", "Apache-2.0", "ISC", "BSD-2-Clause", "BSD-3-Clause", "0BSD", "CC0-1.0"],
     "blocked": ["GPL-2.0-only", "GPL-3.0-only", "AGPL-3.0-only", "SSPL-1.0"],
     "requireReview": ["LGPL-2.1-only", "LGPL-3.0-only", "MPL-2.0", "CC-BY-4.0"]
   }
   

4. Flag violations: Report any dependency with a blocked, unknown, or missing license.

5. Suggest CI integration: Add a license-check step to the CI pipeline that validates all dependencies against the policy.

Summary

After generating all selected documents:

1. List all created files
2. List any install commands needed (TypeDoc, license-checker)
3. Note any manual steps required (filling in placeholders, reviewing runbooks)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.