Skip to content
documentation-audit logo

Documentation Audit

documentation-audit

Use when documentation drift is detected. Comprehensively audits codebase and creates/updates Swagger, features docs, and general documentation to achieve full sync.

SKILL.md

Full skill instructions

Documentation Audit

Overview

Comprehensive documentation sync when drift is detected. Analyzes codebase and creates or updates all documentation artifacts to achieve full synchronization.

Core principle: Documentation must reflect reality. This skill brings them into alignment.

Announce at start: "I'm using documentation-audit to synchronize all documentation with the current codebase."

When This Skill Triggers

This skill is invoked when:

TriggerSource
API documentation driftapi-documentation skill
Features documentation driftfeatures-documentation skill
Missing documentation filesAny documentation check
Manual requestUser or orchestrator

The Audit Process

Phase 1: Discovery

echo "=== Documentation Audit: Discovery Phase ==="

# Find all documentation files
DOC_FILES=$(find . -name "*.md" -o -name "*.yaml" -o -name "*.json" | \
  grep -E "(doc|api|swagger|openapi|feature|guide|readme)" | \
  grep -v node_modules | grep -v .git)

echo "Found documentation files:"
echo "$DOC_FILES"

# Find API documentation
API_DOC=$(find . -name "openapi.yaml" -o -name "swagger.yaml" -o -name "openapi.json" | head -1)
echo "API Documentation: ${API_DOC:-MISSING}"

# Find features documentation
FEATURE_DOC=$(find . -name "features.md" -o -name "FEATURES.md" | head -1)
echo "Features Documentation: ${FEATURE_DOC:-MISSING}"

Phase 2: API Audit

If API endpoints exist:

echo "=== Documentation Audit: API Phase ==="

# Detect API framework
detect_api_framework() {
  if grep -r "express" package.json 2>/​dev/​null; then echo "express"; return; fi
  if grep -r "fastify" package.json 2>/​dev/​null; then echo "fastify"; return; fi
  if grep -r "@nestjs" package.json 2>/​dev/​null; then echo "nestjs"; return; fi
  if grep -r "fastapi" requirements.txt 2>/​dev/​null; then echo "fastapi"; return; fi
  if grep -r "flask" requirements.txt 2>/​dev/​null; then echo "flask"; return; fi
  if [ -f "go.mod" ]; then echo "go"; return; fi
  echo "unknown"
}

FRAMEWORK=$(detect_api_framework)
echo "Detected framework: $FRAMEWORK"

# Extract all endpoints from code
extract_endpoints() {
  case "$FRAMEWORK" in
    express|fastify)
      grep -rh "app\.\(get\|post\|put\|delete\|patch\)" --include="*.ts" --include="*.js" | \
        sed "s/​.*app\.\([a-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    nestjs)
      grep -rh "@\(Get\|Post\|Put\|Delete\|Patch\)" --include="*.ts" | \
        sed "s/​.*@\([A-Za-z]*\)('\([^']*\)'.*/\1 \2/"
      ;;
    fastapi)
      grep -rh "@app\.\(get\|post\|put\|delete\|patch\)" --include="*.py" | \
        sed "s/​.*@app\.\([a-z]*\)(\"\([^\"]*\)\".*/\1 \2/"
      ;;
    *)
      echo "Unknown framework - manual inspection required"
      ;;
  esac
}

ENDPOINTS=$(extract_endpoints)
echo "Found endpoints:"
echo "$ENDPOINTS"

Phase 3: Features Audit

echo "=== Documentation Audit: Features Phase ==="

# Find user-facing components
find_features() {
  # React components in pages/​views
  find . -path "*/​pages/​*" -name "*.tsx" -o -path "*/​views/​*" -name "*.tsx" | \
    xargs -I {} basename {} .tsx 2>/​dev/​null

  # Feature flags
  grep -rh "featureFlag\|feature:" --include="*.ts" --include="*.tsx" | \
    sed "s/​.*['\"]feature[':]\s*['\"]?\([^'\"]*\)['\"]?.*/\1/" 2>/​dev/​null

  # Config options exposed to users
  grep -rh "config\.\|settings\." --include="*.ts" | \
    grep -v "import\|require" | \
    sed "s/​.*\(config\|settings\)\.\([a-zA-Z]*\).*/\2/" 2>/​dev/​null | sort -u
}

FEATURES=$(find_features)
echo "Discovered features:"
echo "$FEATURES"

Phase 4: Generate Missing Documentation

Create OpenAPI if Missing
# Template for new OpenAPI file
openapi: 3.0.3
info:
  title: [PROJECT_NAME] API
  description: |
    API documentation for [PROJECT_NAME].
    Generated by documentation-audit skill.
  version: 1.0.0
  contact:
    name: API Support
servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.example.com
    description: Production server
paths:
  # Endpoints will be added here
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
Create Features Doc if Missing
# Features

> Generated by documentation-audit skill. Update with accurate descriptions.

## Overview

[Brief description of the product]

## Core Features

### [Feature 1]

**Description:** [What it does]

**How to Use:**
1. [Step 1]
2. [Step 2]

---

## Additional Features

[List additional features discovered]

---

*Last updated: [DATE]*
*Note: This file was auto-generated. Review and enhance descriptions.*

Phase 5: Update Existing Documentation

For each discovered but undocumented item:

  1. API Endpoints - Add to OpenAPI spec with:

    • Path and method
    • Parameters (from function signature)
    • Request body schema (from DTO/​type)
    • Response schema (from return type)
    • Basic description
  2. Features - Add to features doc with:

    • Feature name
    • Basic description
    • Placeholder for how-to-use
    • Note to review and enhance

Phase 6: Validation

echo "=== Documentation Audit: Validation Phase ==="

# Validate OpenAPI
if [ -f "openapi.yaml" ]; then
  yq '.' openapi.yaml > /​dev/​null 2>&1 && echo "OpenAPI: Valid YAML" || echo "OpenAPI: Invalid YAML"
fi

# Validate Markdown
for file in docs/​*.md; do
  if [ -f "$file" ]; then
    # Check for required sections
    if ! grep -q "^## " "$file"; then
      echo "WARNING: $file missing section headers"
    fi
  fi
done

# Check completeness
ENDPOINTS_DOCUMENTED=$(yq '.paths | keys | length' openapi.yaml 2>/​dev/​null || echo 0)
ENDPOINTS_IN_CODE=$(extract_endpoints | wc -l)

echo "Endpoints in code: $ENDPOINTS_IN_CODE"
echo "Endpoints documented: $ENDPOINTS_DOCUMENTED"

if [ "$ENDPOINTS_DOCUMENTED" -lt "$ENDPOINTS_IN_CODE" ]; then
  echo "WARNING: Some endpoints still undocumented"
fi

Audit Report

Post audit results to GitHub issue:

## Documentation Audit Complete

**Audit Date:** [ISO_TIMESTAMP]
**Triggered By:** [api-documentation|features-documentation|manual]

### Summary

| Category | Before | After | Status |
|----------|--------|-------|--------|
| API Endpoints | [N] undocumented | [N] documented | [COMPLETE/​PARTIAL] |
| Features | [N] undocumented | [N] documented | [COMPLETE/​PARTIAL] |
| General Docs | [N] missing | [N] created | [COMPLETE/​PARTIAL] |

### Files Created
- `openapi.yaml` - API documentation
- `docs/​features.md` - Features documentation

### Files Updated
- `openapi.yaml` - Added [N] endpoints
- `docs/​features.md` - Added [N] features

### Requires Manual Review
- [ ] Verify API response schemas
- [ ] Enhance feature descriptions
- [ ] Add usage examples
- [ ] Review security documentation

### Next Steps
1. Review generated documentation
2. Add detailed descriptions
3. Include examples
4. Validate with stakeholders

---
*documentation-audit skill completed*

Checklist

During audit:

  • All documentation files discovered
  • API framework detected
  • All endpoints extracted from code
  • All features extracted from code
  • Missing documentation files created
  • Existing documentation updated
  • All files validated
  • Audit report posted to issue
  • Changes committed

Quality Standards

Generated documentation must meet:

StandardRequirement
CompletenessEvery endpoint/​feature listed
ValidityYAML/​JSON validates
StructureRequired sections present
PlaceholdersClear markers for manual review
AttributionGenerated by skill noted

Integration

This skill is invoked by:

SkillWhen
api-documentationAPI drift detected
features-documentationFeatures drift detected
issue-driven-developmentDocumentation step

This skill uses:

ToolPurpose
Glob/​GrepDiscover code artifacts
ReadAnalyze existing docs
WriteCreate new docs
EditUpdate existing docs
yqValidate YAML
jqValidate JSON

More Productivity & Planning skills

brainstorming logo
Productivity & Planning

brainstorming

Structured design dialogue that validates ideas before implementation begins.

295.4K 385.7K
View
ui-ux-pro-max logo
Productivity & Planning

ui-ux-pro-max

Comprehensive design intelligence for web and mobile UI/UX across 10 technology stacks.

133.1K 383.9K
View
writing-plans logo
Productivity & Planning

writing-plans

Comprehensive implementation plans for multi-step tasks, breaking down specs into bite-sized, testable steps.

295.4K 268K
View
using-superpowers logo
Productivity & Planning

using-superpowers

Introduction to the obra skills system with mandatory skill invocation rules and best practices.

295.4K 259.8K
View
executing-plans logo
Productivity & Planning

executing-plans

Execute a written implementation plan with critical review and task checkpoints.

295.4K 229.1K
View
dispatching-parallel-agents logo
Productivity & Planning

dispatching-parallel-agents

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K
View
using-git-worktrees logo
Productivity & Planning

using-git-worktrees

Isolated git worktrees with smart directory selection and safety verification.

295.4K 205.2K
View
webapp-testing logo
Productivity & Planning

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

179.7K 170.6K
View
content-strategy logo
Productivity & Planning

content-strategy

Plan searchable and shareable content that drives traffic, builds authority, and generates leads.

53.3K 150.9K
View
repo-intake-and-plan logo
Productivity & Planning

repo-intake-and-plan

README-first repository scanner that extracts commands and classifies reproduction candidates without executing them.

497 139.6K
View
marketing-ideas logo
Productivity & Planning

marketing-ideas

Brainstorm and prioritize marketing strategies tailored to your SaaS stage, budget, and goals.

53.3K 137.2K
View
site-architecture logo
Productivity & Planning

site-architecture

Plan and optimize your website's page hierarchy, navigation, URL structure, and internal linking.

53.3K 112.8K
View

Productivity AI tools

Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View
SaveDay logo
Productivity

SaveDay

Capture, organize, and utilize your knowledge effortlessly.

Free
View
Any Summary logo
Productivity

Any Summary

Instant Summaries of Audio & Video Interviews with AnySummary

Freemium
View
M
Productivity

Map This

Transform PDFs into engaging mind maps.

Freemium
View
ChatPDF logo
Productivity

ChatPDF

Chat with any PDF instantly

Free
View
I
Productivity

intellisay

Create an optimal daily plan using your voice

Paid
View
A
Productivity

Aurora AI

A productivity platform to centralize organizational knowledge and workflows with contextual AI assistance.

Paid
View
AskYourPDF logo
Productivity

AskYourPDF

AskYourPDF Pricing Plans: Tailored to Your Needs

Free
View