home / skills / phrazzld / claude-config / update-docs

update-docs skill

safe

/skills/update-docs

This skill audits codebase documentation gaps and generates comprehensive docs across high level, module, decisions, and diagrams to reduce cognitive load.

npx playbooks add skill phrazzld/claude-config --skill update-docs

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.7 KB

---
name: update-docs
description: |
  Comprehensive documentation audit and generation.
  Launches parallel agents for high-level docs, module-level docs, decision records, and state diagrams.
  Use when: documentation gaps, post-implementation docs, README updates, architecture docs.
effort: high
---

# /update-docs

Documentation is design. Missing docs are missing understanding.

## Role

Documentation architect. Codex drafts, specialized agents audit each aspect, you review and approve.

## Objective

Audit the codebase for documentation gaps. Create what's missing. Update what's stale. Delete what misleads.

## Latitude

- Delegate drafting to Codex (high-volume writing)
- Launch 4 parallel agents for different doc aspects
- Prioritize state diagrams for stateful components
- Skip elegance in pursuit of coverage

## Philosophy

- Write docs at the moment of maximum understanding
- Good docs reduce cognitive load — make the system feel *smaller*
- Document abstractions, not implementation
- State diagrams force systematic thinking

## Workflow

Launch 4 parallel Task agents:

1. **High-Level Docs** — README, ARCHITECTURE.md, CLAUDE.md, ADR infrastructure
2. **Module-Level Docs** — Per-module READMEs, deep vs shallow detection, navigation guides
3. **Decision Records** — Scan git history + codebase for undocumented non-obvious decisions
4. **State & Flow Diagrams** — Mermaid diagrams for stateful components and complex flows

See `references/agent-prompts.md` for detailed agent instructions.

## Guiding Principle

"Write the document that makes the codebase smaller."

## Output

Summary: docs created, docs updated, flagged items needing user input, items already good. Commit if changes made.

Overview

This skill performs a comprehensive documentation audit and generates missing or stale docs across a codebase. It launches parallel agents to tackle README and architecture content, per-module docs, decision records, and state/flow diagrams. The output is a clear summary of created, updated, and flagged items, ready to commit.

How this skill works

I act as the documentation architect and coordinate four parallel task agents: high-level docs, module-level docs, decision records, and state & flow diagrams. Each agent scans the codebase and git history, drafts content (using automated drafting where appropriate), and reports items that need human review or input. I review and approve the drafts, prioritize state diagrams for stateful components, and prepare a commit-ready changeset.

When to use it

When the project README is missing, outdated, or unclear
After implementation milestones to capture design decisions
When you suspect documentation gaps in modules or navigation
To generate or update architecture and system-level docs
Before onboarding new contributors or preparing releases

Best practices

Run the audit at the moment of maximum understanding, ideally right after a feature lands
Prioritize documenting abstractions and system behavior over implementation details
Accept pragmatic, correct coverage first; iterate later for elegance
Resolve flagged items quickly by providing context or decisions to the agent
Use generated Mermaid state diagrams for complex or stateful components

Example use cases

Create a full project README, architecture overview, and contributor guide for a newly merged project
Produce per-module READMEs and navigation guides in a large monorepo with uneven docs
Scan git history to extract undocumented non-obvious decisions and convert them to ADRs
Generate Mermaid state diagrams for services with complex lifecycle or state transitions
Update stale documentation after a refactor and list files requiring manual confirmation

FAQ

What does the skill commit automatically?

It prepares a commit of created and updated docs; commits occur only after review and approval.

How are decision records generated?

The agent scans recent commits and code patterns for non-obvious choices, drafts ADRs, and flags items needing developer context.