docs-revise

Revises outdated documentation to match the current codebase and removes obsolete files.

4|Updated Feb 9, 2021
One-click install
npx skills add https://github.com/breengles/poor-man-OS-setup --skill docs-revise
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-revise
Source: https://github.com/breengles/poor-man-OS-setup/tree/main/.claude/skills/docs-revise
Command: npx skills add https://github.com/breengles/poor-man-OS-setup --skill docs-revise

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It prevents documentation from drifting out of date by reconciling existing docs with the current codebase so readers don’t follow stale APIs or incorrect instructions.

Core Features & Use Cases

  • Scope-aware revisions: Revise a single doc file by path (e.g., docs/api.md), a doc by component name (docs/<name>.md), or all files under docs/ when no argument is provided.
  • Code-to-doc discrepancy detection: Compare what docs claim against what the source code actually does, including stale content, missing features, incorrect descriptions, broken references, and newly added components.
  • Documentation lifecycle management: Update docs/README.md when needed, delete obsolete docs, and create missing docs for components that exist in code but lack documentation.
  • Quality formatting: Reformat updated Markdown files using Prettier for consistent style.

Quick Start

Ask docs-revise to revise all documentation files in the docs/ directory for the current state of the repository.

Frequently Asked Questions about docs-revise

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update stale documentation to match my current codebase?

To update stale documentation, you can reconcile existing markdown files with your current codebase by revising content based on recent git history and source code, ensuring API documentation accurately reflects actual project functionality.

What is the best way to find missing documentation for newly added code components?

Finding missing documentation involves comparing the docs directory against the source code to identify undocumented modules, allowing you to create missing markdown files and update the docs README to cover newly discovered components.

How do I revise a specific markdown file by component name or file path?

You can revise a specific markdown file by targeting its path or component name, which scopes the documentation update to check for broken references and incorrect descriptions in that single file.

Does this documentation revision process format markdown with Prettier?

Yes, the documentation revision process formats updated markdown files using Prettier, ensuring consistent style and formatting across all created or updated project documentation after reconciling with the codebase.

Can I update all files under the docs directory at once?

Yes, you can update all files under the docs directory at once by running the revision scope without specific arguments, which triggers a full code-to-doc discrepancy detection across the entire documentation directory.

When should I remove obsolete documentation from my repository?

You should remove obsolete documentation when the corresponding source code has been deleted, allowing the revision process to identify broken references and delete obsolete markdown files to prevent documentation drift and keep docs accurate.