Technical Docs

Documentation

Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.

When to use: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.

When NOT to use: Writing marketing copy, blog posts, or content that does not live alongside code.

Quick Reference

Common Mistakes

Delegation

• Scan codebase for undocumented exports and documentation gaps: Use Explore agent
• Generate a full documentation site with diagrams from an existing codebase: Use Task agent
• Plan documentation architecture and information hierarchy for a new project: Use Plan agent

If the mermaid-diagrams skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it.

Otherwise, recommend: npx skills add oakoss/agent-skills --skill mermaid-diagrams

If the tldr-expert skill is available, delegate summary and brief generation to it.

References

• Writing Style -- Voice, tone, formatting rules, error message guidelines, and structural standards
• Mermaid Diagrams -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
• Doc Coverage -- Feature inventory, gap analysis, code-first and doc-first audit workflows
• AI Collaboration -- AI-human doc workflow, hallucination handling, documentation-as-code practices
• Markdown Standards -- Frontmatter, headings, code blocks, tables, callouts, and link conventions
• Runbooks and Onboarding -- Incident runbook templates, escalation paths, and developer onboarding guides

Role of the AI Agent

Role of the Human Editor

The AI-First Workflow

1. Code commit: Developer pushes code with docstrings 2. Sync audit: Docs skill identifies new features lacking documentation 3. AI drafting: AI generates a draft page based on code analysis 4. Human review: Expert reviews, edits, and approves the draft 5. Merge: Documentation integrates into the main branch

Documentation as Code (DaC)

• Docs live in the same repository as the code
• CI/CD pipelines lint documentation alongside code
• Use bundled code context when asking AI to write documentation
• Version-control documentation changes with the same rigor as code

Handling Hallucinations

When AI generates incorrect documentation:

Trace the Source

Determine whether the AI misinterpreted a comment, guessed a default value, or fabricated a feature.

Fix the Source

Update the code docstrings to be more explicit. Ambiguous comments produce ambiguous documentation.

Update the Instructions

Provide more context in the documentation skill instructions to prevent recurrence.

Quality Verification

Before merging AI-generated documentation:

Feature Inventory Targets

Scan the codebase for these documentation-worthy items:

• Public exports: classes, functions, types, and module entry points
• Configuration options: *Settings types, default config objects, builder patterns
• Environment variables or runtime flags
• CLI commands, scripts, and example entry points
• User-facing behaviors: retry, timeouts, streaming, errors, logging, telemetry
• Deprecations, removals, or renamed settings

Doc-First Pass

Review each documentation page and check for:

• Missing opt-in flags, env vars, or customization options the page implies
• New features that belong on that page based on user intent and navigation
• Outdated defaults or removed options still referenced

Code-First Pass

Map features to the closest existing page based on the docs navigation:

• Prefer updating existing pages over creating new ones unless the topic is clearly new
• Use conceptual pages for cross-cutting concerns (auth, errors, streaming, tracing, tools)
• Keep quick-start flows minimal; move advanced details into deeper pages

Doc Sync Audit

Compare current code against documentation to find drift:

# Diff current branch against main
git diff main...HEAD -- src/

# Find undocumented exports
rg "export (const|function|class)" src/ --type ts

# Compare with docs structure
ls -R docs/

Evidence Capture

When documenting gaps:

• Record the file path and symbol/setting name
• Note defaults or behavior-critical details for accuracy checks
• Avoid large code dumps; a short identifier is enough

Red Flags for Outdated Docs

When to Propose Structural Changes

• A page mixes unrelated audiences (quick-start + deep reference) without separation
• Multiple pages duplicate the same concept without cross-links
• New feature areas have no obvious home in the navigation structure

Diff Mode Guidance

When auditing a feature branch against main:

• Focus only on changed behavior: new exports, modified defaults, removed features, renamed settings
• Use git diff main...HEAD to constrain analysis
• Document removals explicitly so docs can be pruned

Patch Guidance

• Keep edits scoped and aligned with existing tone and format
• Update cross-links when moving or renaming sections
• Leave translated docs untouched; English-only updates

README Structure Template

A README is the front door to a project. It answers: what is this, how do I use it, and where do I go for more. Keep under 200 lines; link out for depth.

````markdown

Project Name

  

One-line description of what this project does and who it's for.

Quick Start

npm install package-name

import { createClient } from 'package-name';

const client = createClient({ apiKey: process.env.API_KEY });
const result = await client.doSomething({ input: 'hello' });
console.log(result);

Installation

# npm
npm install package-name

# pnpm
pnpm add package-name

# yarn
yarn add package-name

Requirements

• Node.js >= 20
• TypeScript >= 5.0 (optional but recommended)

Usage

Configuration Options

API Reference

See the full API documentation.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT ````

Key Principles

• Badges first — CI status, version, license give instant project health signals
• One-line description — no jargon, no marketing; what it does in plain language
• Quick start before full install — most users want to copy-paste and go
• Tables for config — scannable, consistent, easy to maintain
• Link out for depth — README stays under 200 lines; detailed docs live elsewhere

Architecture Decision Records (ADRs)

ADRs capture the WHY behind significant technical decisions. They are immutable once accepted: supersede rather than edit.

When to Write an ADR

• Choosing a framework, database, or major dependency
• Changing authentication or authorization strategy
• Adopting or dropping a pattern (monorepo, microservices, etc.)
• Any decision that a new team member would question

ADR Template

# ADR-001: Use PostgreSQL for Primary Data Store

## Status

Accepted

## Context

The application requires ACID transactions, complex queries with joins,
and strong consistency guarantees. The team has production experience with
PostgreSQL. Current data volume is ~10GB with projected growth to 500GB
over 2 years.

## Decision

Use PostgreSQL 16 as the primary data store, accessed via Prisma ORM.

## Consequences

### Positive

- ACID compliance for financial transaction data
- Rich query capabilities (JSON, full-text search, CTEs)
- Team familiarity reduces onboarding time

### Negative

- Horizontal scaling requires read replicas or sharding
- Schema migrations need coordination across services
- Higher operational overhead than managed NoSQL options

### Neutral

- Need to establish backup and disaster recovery procedures
- Connection pooling (PgBouncer) required above ~100 concurrent connections

Numbering and Organization

docs/
  adr/
    README.md          # Index of all ADRs with status
    adr-001-database.md
    adr-002-auth.md
    adr-003-monorepo.md

Status Lifecycle

Proposed → Accepted → [Deprecated | Superseded by ADR-XXX]

Never delete or edit accepted ADRs. To reverse a decision, write a new ADR that supersedes the old one and update the status of the original.

Changelog (Keep a Changelog)

Follow Keep a Changelog format, aligned with semantic versioning.

Template

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added

- New `retries` configuration option for automatic retry on failure

### Fixed

- Connection timeout now respects the configured `timeout` value

## [2.1.0] - 2025-03-15

### Added

- Batch processing support via `client.batchProcess()`
- TypeScript 5.5 support

### Changed

- Default timeout increased from 10s to 30s

### Deprecated

- `client.process()` single-item method; use `client.batchProcess()` instead

## [2.0.0] - 2025-01-10

### Changed

- **BREAKING:** Renamed `createInstance` to `createClient`
- **BREAKING:** Minimum Node.js version is now 20

### Removed

- **BREAKING:** Dropped CommonJS support; ESM only

[Unreleased]: https://github.com/org/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0

Categories

Auto-generation from Conventional Commits

Document Metadata (Frontmatter)

All major documentation files should include YAML frontmatter:

---
title: Page Title
description: Concise description for SEO and AI indexing.
tags: [tag1, tag2]
---

Headings

• H1: Only one per page, used for the main title
• H2: Major sections
• H3: Sub-sections
• No skipping: Never skip a level (do not go from H1 to H3)

Code Blocks

Always specify the language for fenced code blocks:

Use meaningful variable names in examples. Add comments within code blocks to explain complex logic.

Showing Changes

Use diff syntax for before/after comparisons:

- const oldWay = true;
+ const newWay = 2026;

Tables

Use tables for data comparison, configuration options, and anti-pattern lists:

| Option     | Type     | Default | Description          |
| :--------- | :------- | :------ | :------------------- |
| `maxDepth` | `number` | `3`     | Maximum crawl depth. |

Callouts

Use standard blockquote syntax for callouts:

• > [!NOTE] -- Additional context
• > [!WARNING] -- Potential issues
• > [!IMPORTANT] -- Critical information

Use callouts sparingly to avoid diluting their impact.

Links and Paths

• Internal links: Always use relative paths (./other-page.md)
• External links: Use absolute URLs
• Descriptive text: Never use "click here"; describe the destination
• Validation: Periodically run a link-checker to prevent broken links

Task Lists

Use [x] and [ ] for progress tracking:

- [x] Write overview section
- [ ] Add code examples
- [ ] Review for accuracy

AI Indexing Optimization

To make docs discoverable by AI agents:

• Use semantic keywords in headings
• State the subject of the page in the first paragraph
• Include a glossary or definitions section for custom terminology

Core Principle

Never use static images for technical docs. Use raw Mermaid syntax in Markdown. Store complex, reusable diagrams in .mermaid files under assets/.

Diagram Type Selection

Sequence Diagrams

Use autonumber, activate/deactivate, and Note to make interactions explicit. Map every message to a specific function call or network request.

sequenceDiagram
    autonumber
    participant U as User
    participant A as Agent
    participant S as Skill Registry

    U->>+A: Request Task
    A->>+S: Fetch Expert Skill
    S-->>-A: SKILL.md Content
    Note over A: Orchestrating subtasks...
    A->>U: Deliver Solution
    deactivate A

Entity-Relationship Diagrams

Use Crow's Foot notation. Always include data types and PK/FK indicators. Derive ERDs from Drizzle/Prisma schemas to prevent drift.

erDiagram
    USER ||--o{ POST : writes
    USER {
        string id PK
        string email
        string name
    }
    POST {
        string id PK
        string title
        string content
        string authorId FK
    }

Gitgraph Diagrams

Use for PR descriptions involving complex branching. Standardize on main, develop, and feature/* branch naming.

gitGraph
    commit id: "Initial"
    branch feature/oidc
    checkout feature/oidc
    commit id: "Add OIDC"
    checkout main
    merge feature/oidc tag: "v1.0.0"
    commit id: "Hotfix"

Kanban Diagrams

Visualize task workflow states with columns and task metadata:

kanban
  Todo
    [Design schema]
    [Write tests]
  In Progress
    [Implement API]@{ assigned: 'alice', priority: 'High' }
  Done
    [Set up CI]

Architecture Diagrams

Map system topology with services and connections:

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service server(server)[Server] in api
    service disk(disk)[Storage] in api

    db:L -- R:server
    server:L -- R:disk

Anti-Patterns

Managing Complexity

When a diagram becomes cluttered:

1. Break into multiple focused diagrams 2. Use subgraphs for grouping related nodes 3. Change layout direction (TD to LR or vice versa) 4. Limit to 15-20 nodes per diagram

Troubleshooting

Mermaid Render Failures

Symptom: Diagram renders as raw text or errors.

Common causes:

• Missing participant declarations
• Unmatched activate/deactivate pairs
• Unsupported syntax in older renderers

Fix: Validate syntax with the Mermaid Live Editor or a verification script.

ERD Schema Drift

Symptom: ERD no longer matches database schema.

Fix: Regenerate from Drizzle/Prisma schema. Diff the output against the committed .mermaid file.

Runbooks

Runbooks are for 3 AM incidents. They must be unambiguous, step-by-step, and assume the reader is stressed and unfamiliar with the system.

Runbook Template

# Runbook: Database Connection Pool Exhaustion

## Symptoms

- API responses timing out (>30s)
- Error logs: `PrismaClientKnowledgeBaseError: Timed out waiting for connection`
- Monitoring: Connection pool utilization > 95%

## Severity

High — user-facing degradation

## Diagnosis

1. Check connection pool metrics in Grafana: `Dashboard > DB > Pool`
2. Identify top queries by duration:

` ` `bash
psql -c "SELECT pid, now() - query_start AS duration, query
         FROM pg_stat_activity
         WHERE state = 'active'
         ORDER BY duration DESC
         LIMIT 10;"
` ` `

3. Check for long-running transactions:

` ` `bash
psql -c "SELECT pid, now() - xact_start AS duration
         FROM pg_stat_activity
         WHERE xact_start IS NOT NULL
         ORDER BY duration DESC
         LIMIT 5;"
` ` `

## Resolution

### Step 1: Kill long-running queries (immediate relief)

` ` `bash
psql -c "SELECT pg_terminate_backend(pid)
         FROM pg_stat_activity
         WHERE duration > interval '5 minutes'
         AND state = 'active';"
` ` `

### Step 2: Increase pool size (temporary)

Update the `DATABASE_POOL_SIZE` env var and restart the service:

` ` `bash
kubectl set env deployment/api DATABASE_POOL_SIZE=20
kubectl rollout restart deployment/api
` ` `

### Step 3: Identify root cause

Review recent deployments for new queries or missing indexes.

## Escalation

- **L1**: On-call engineer (this runbook)
- **L2**: Database team (#db-team in Slack)
- **L3**: Infrastructure lead (page via PagerDuty)

## Prevention

- Set connection pool alerts at 80% utilization
- Require `EXPLAIN ANALYZE` for new queries touching large tables
- Add query timeout: `statement_timeout = '30s'`

Key Principles

• Symptoms first — start with what the reader is seeing
• Copy-paste commands — no pseudocode, no "run the appropriate command"
• Escalation paths — who to contact when the runbook does not resolve the issue
• Prevention section — turn incidents into improvements

Onboarding Guide

An onboarding guide reduces the time from "git clone" to "first meaningful contribution."

Template

# Developer Onboarding

## Prerequisites

- Node.js >= 20 (use `nvm install` with the project's `.nvmrc`)
- pnpm >= 9
- Docker (for local database)

## First-Time Setup

` ` `bash
git clone https://github.com/org/repo.git
cd repo
pnpm install
cp .env.example .env.local    # Edit with your local values
pnpm db:setup                 # Start database and run migrations
pnpm dev                      # Start dev server at localhost:3000
` ` `

## Project Structure

` ` `sh
src/
  app/          # Next.js app router pages
  components/   # Shared UI components
  lib/          # Business logic and utilities
  server/       # API routes and server-side code
` ` `

## Key Concepts

- **Feature flags**: Managed via LaunchDarkly. See `src/lib/flags.ts`.
- **Database**: PostgreSQL via Prisma. Schema at `prisma/schema.prisma`.
- **Auth**: NextAuth.js with OAuth providers. Config at `src/lib/auth.ts`.

## Common Tasks

| Task             | Command               |
| ---------------- | --------------------- |
| Run dev server   | `pnpm dev`            |
| Run tests        | `pnpm test`           |
| Run linter       | `pnpm lint`           |
| Generate types   | `pnpm codegen`        |
| Create migration | `pnpm db:migrate:dev` |
| Reset database   | `pnpm db:reset`       |

## Your First Contribution

1. Pick an issue labeled `good-first-issue`
2. Create a branch: `git checkout -b feat/your-feature`
3. Make changes and add tests
4. Run `pnpm test && pnpm lint` before committing
5. Open a PR against `main`

Key Principles

• Test the guide — have a new team member follow it; fix every stumbling block
• Keep it current — outdated setup instructions are worse than none
• Link, don't duplicate — reference existing docs rather than copying content
• Include common tasks — the commands developers run daily

Voice and Tone

Active Voice

Always prefer active voice:

• Bad: "The function is called by the agent."
• Good: "The agent calls the function."

Direct and Concise

Avoid fluff. Start with the most important information. Use simple words for complex concepts.

Inclusive Language

Use gender-neutral pronouns (they/them) or avoid pronouns entirely. Use "users" or "developers" instead of "the user." Avoid obscure jargon unless defined.

Structural Standards

The Rule of Three

Limit heading hierarchies to H1, H2, and H3. If you need H4, consider splitting the page.

Executive Summary

Every page longer than 500 words must start with a brief summary or table of contents.

Contextual Links

Use descriptive link text:

• Bad: "Click this link to read more."
• Good: "See the Authentication Guide for details."

Formatting Rules

Error Message Guidelines

Model error messages as "Problem, Cause, Solution":

Documentation Quality Standards

• Clarity: Active voice, present tense, direct address
• Accuracy: Code examples must be tested and valid
• Discoverability: Every page listed in nav config with a descriptive title

Feature Release Doc Checklist

Every new feature needs these four sections:

1. Overview: What it does and why it exists 2. Configuration: All env vars, settings, and defaults 3. Examples: Quick-start and advanced code blocks 4. Troubleshooting: Common errors and fixes

API Reference Update Flow

1. Update JSDoc/TSDoc in source code 2. Run doc generator (e.g., make build-docs) 3. Verify output matches Markdown standards

JSDoc / TSDoc Patterns

When to Document

Good JSDoc Examples

/**
 * @returns Amount in cents, not dollars
 */
export function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

/**
 * Deletes the user and all associated data (posts, comments, sessions).
 * Triggers a `user.deleted` webhook after successful deletion.
 *
 * @throws {NotFoundError} If user does not exist
 * @throws {ForbiddenError} If caller lacks admin role
 */
export async function deleteUser(id: string): Promise<void> {
  // ...
}

/**
 * @param ttl - Cache duration in seconds
 * @default ttl 3600
 */
export function setCacheControl(ttl?: number): void {
  // ...
}

JSDoc to Skip

// Types already communicate everything here
export function getUserById(id: string): Promise<User | null> {
  return db.user.findUnique({ where: { id } });
}

// Obvious getter
export function getFullName(user: User): string {
  return `${user.firstName} ${user.lastName}`;
}

Component Prop Documentation

Document on the type, not the component function:

type AlertProps = {
  /** @default "info" */
  variant?: 'info' | 'warning' | 'error' | 'success';
  /** Dismissible alerts show a close button */
  dismissible?: boolean;
  /** Called when the alert is dismissed; required if `dismissible` is true */
  onDismiss?: () => void;
  children: React.ReactNode;
};

function Alert({
  variant = 'info',
  dismissible,
  onDismiss,
  children,
}: AlertProps) {
  // ...
}

Code Documentation Hierarchy

1. Self-documenting code first — rename variables, extract functions, simplify logic 2. Types second — let TypeScript signatures communicate contracts 3. Tests third — tests document behavior and edge cases 4. Comments last — only when the code genuinely cannot explain itself