documentation-maintainer

name	documentation-maintainer
description	> Use when this capability is needed.

When to activate

After API changes, when behavior changes, when someone says "the docs are wrong", before releases.

When NOT to activate

• Code-only changes with no external behavior change
• Comments in code (write them inline, not here)

Doc drift detection

Signs of doc drift:

• Function signature in README doesn't match code
• Example code in docs fails to run
• ENV vars listed in docs don't match .env.example
• CLI commands in docs produce different output
• API response shape changed but docs show old format

# Find potentially stale documentation
git log --all --oneline --diff-filter=M -- src/ | head -20
# Then check if matching docs were updated in the same commit

README structure (minimal but complete)

# [Project Name]

One sentence: what this does and why it exists.

## Quick start

\`\`\`bash
npm install -g myapp
myapp init --yes
myapp --help
\`\`\`

## Installation

## Usage (with real examples, not pseudocode)

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| DATABASE_URL | yes | — | PostgreSQL connection string |
| PORT | no | 3000 | HTTP server port |

## API Reference (link to full docs or include here)

## Contributing

## License

FAIL: Placeholder README

# MyProject
This project does amazing things!
## Features
- Feature 1
- Feature 2
## Usage
See the docs for more information.

ADR (Architecture Decision Record) template

# ADR-NNN: [Decision title]

**Date:** YYYY-MM-DD  
**Status:** accepted | proposed | deprecated | superseded by ADR-NNN  
**Deciders:** [names]

## Context
[What is the problem or situation that prompted this decision?]

## Decision
[What was decided?]

## Rationale
[Why was this decided? What alternatives were considered?]

## Consequences
**Positive:**
- [Effect 1]

**Negative:**
- [Effect 1]

## References
- [Links to discussions, related issues, external resources]

Changelog from git (keep-a-changelog format)

# Changelog

## [Unreleased]
### Added
### Changed
### Deprecated
### Removed
### Fixed
### Security

## [1.2.0] - 2025-01-15
### Added
- `omnix error-match` command for finding past error fixes
### Changed
- `retrieve-context` now uses task-type-aware retrieval modes
### Fixed
- Token budget enforcement now works correctly in debugging mode

# Generate from git history
git log --oneline --no-merges v1.1.0..HEAD --pretty=format:"- %s"

API documentation (OpenAPI auto-generation)

// Example: Hono + Zod + OpenAPI
import { swaggerUI } from '@hono/swagger-ui';
import { z } from 'zod';

app.openapi(
  createRoute({
    method: 'get',
    path: '/users/{id}',
    request: { params: z.object({ id: z.string() }) },
    responses: {
      200: { content: { 'application/json': { schema: UserSchema } } },
      404: { content: { 'application/json': { schema: ErrorSchema } } },
    },
  }),
  (c) => { ... }
);
app.get('/docs', swaggerUI({ url: '/doc' }));

Runbook template

# Runbook: [Service/Operation Name]

**Last updated:** YYYY-MM-DD  
**On-call contact:** [name/channel]

## Service overview
[1-2 sentences: what this service does, why it's critical]

## Common alerts and responses

### Alert: HighErrorRate
**Trigger:** Error rate > 5% for 5 minutes  
**Steps:**
1. Check logs: `kubectl logs -l app=myapp --tail=100`
2. Check recent deploys: `helm history myapp`
3. If recent deploy: `helm rollback myapp 0`
4. Escalate if not resolved in 15 minutes

## Deployment
[Step-by-step deploy instructions]

## Rollback
[Step-by-step rollback instructions]

Verification

• All code examples in docs actually run
• ENV vars in docs match .env.example
• API docs match actual API responses
• Changelog updated for user-visible changes
• ADR written for significant architecture decisions

---

Source: Abhiram1106/omnix — distributed by TomeVault.